توثيق إعدادات Intlayer

import { Locales, type IntlayerConfig } from "intlayer";
import { nextjsRewrite } from "intlayer/routing";
import { syncJSON } from "@intlayer/sync-json-plugin";
import { z } from "zod";

/**
 * مثال لملف إعدادات Intlayer مع جميع الخيارات المتاحة.
 */
const config: IntlayerConfig = {
  /**
   * إعدادات التدويل (Internationalization).
   */
  internationalization: {
    /**
     * قائمة اللغات المدعومة في التطبيق.
     * الافتراضي: [Locales.ENGLISH]
     */
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],

    /**
     * قائمة اللغات المطلوبة التي يجب تعريفها في كل قاموس.
     * إذا كانت فارغة، فستكون جميع اللغات مطلوبة في وضع `strict`.
     * الافتراضي: []
     */
    requiredLocales: [Locales.ENGLISH],

    /**
     * مستوى الصرامة للمحتوى المترجم.
     * - "strict": يلقي خطأ إذا كانت اللغة المعلنة مفقودة أو غير معلنة.
     * - "inclusive": يلقي تحذيراً إذا كانت اللغة المعلنة مفقودة.
     * - "loose": يقبل أي لغة موجودة.
     * الافتراضي: "inclusive"
     */
    strictMode: "inclusive",

    /**
     * اللغة الافتراضية المستخدمة كاحتياطي في حالة عدم العثور على اللغة المطلوبة.
     * الافتراضي: Locales.ENGLISH
     */
    defaultLocale: Locales.ENGLISH,
  },

  /**
   * الإعدادات التي تتحكم في عمليات القاموس والسلوك عند فقدان المحتوى.
   */
  dictionary: {
    /**
     * يتحكم في طريقة استيراد القواميس.
     * - "static": استيراد ثابت أثناء البناء.
     * - "dynamic": استيراد ديناميكي باستخدام Suspense.
     * - "fetch": جلب ديناميكي عبر Live Sync API.
     * الافتراضي: "static"
     */
    importMode: "static",

    /**
     * إستراتيجية الملء التلقائي للترجمات المفقودة باستخدام الذكاء الاصطناعي.
     * يمكن أن تكون قيمة منطقية أو نمط مسار لحفظ المحتوى المملوء.
     * الافتراضي: true
     */
    fill: true,

    /**
     * الموقع الفعلي لملفات القاموس.
     * - "local": مخزنة في نظام الملفات المحلي.
     * - "remote": مخزنة في Intlayer CMS.
     * - "hybrid": مخزنة محلياً وفي Intlayer CMS.
     * - "plugin" (أو أي سلسلة مخصصة): يتم توفيرها بواسطة إضافة أو مصدر مخصص.
     * الافتراضي: "local"
     */
    location: "local",

    /**
     * ما إذا كان سيتم تحويل المحتوى تلقائياً (مثلMarkdown إلى HTML).
     * الافتراضي: false
     */
    contentAutoTransformation: false,
  },

  /**
   * إعدادات التوجيه والبرمجيات الوسيطة.
   */
  routing: {
    /**
     * إستراتيجية التوجيه حسب اللغة.
     * - "prefix-no-default": بادئة لجميع اللغات باستثناء الافتراضية (مثلاً: /dashboard، /fr/dashboard).
     * - "prefix-all": بادئة لجميع اللغات (مثلاً: /en/dashboard، /fr/dashboard).
     * - "no-prefix": لا توجد لغة في رابط URL.
     * - "search-params": استخدام ?locale=...
     * الافتراضي: "prefix-no-default"
     */
    mode: "prefix-no-default",

    /**
     * يفعّل وكيل توجيه اللغات في Intlayer (البرمجية الوسيطة).
     * يتولى اكتشاف اللغة وإعادة التوجيه وإعادة الكتابة في dev وpreview وSSR.
     * - غير محدد (auto): تُبقي خوادم dev وpreview التوجيه معتمدًا على الرابط،
     *   متجاهلةً اللغة المخزّنة في ملفات تعريف الارتباط والترويسات. تظل البادئات
     *   تُحلّ، وتظل اللغة تُحفظ، ويظل اكتشاف Accept-Language ساريًا.
     *   في الإنتاج يتصرف مثل `true`.
     * - true: السلوك الكامل في جميع البيئات.
     * - false: بدون توجيه للغات.
     * الافتراضي: undefined (auto)
     */
    enableProxy: undefined,

    /**
     * أين يتم تخزين اللغة التي يختارها المستخدم.
     * الخيارات: 'cookie' أو 'localStorage' أو 'sessionStorage' أو 'header' أو مصفوفة منها.
     * الافتراضي: ['cookie', 'header']
     */
    storage: ["cookie", "header"],

    /**
     * المسار الأساسي لروابط التطبيق.
     * الافتراضي: ""
     */
    basePath: "",

    /**
     * قواعد إعادة كتابة رابط URL مخصصة للمسارات في لغات معينة.
     */
    rewrite: nextjsRewrite({
      "/[locale]/about": {
        en: "/[locale]/about",
        fr: "/[locale]/a-propos",
      },
    }),

    /**
     * يربط اللغات بأسماء نطاقات الاستضافة للتوجيه القائم على النطاق.
     * ستكون روابط URL لهذه اللغات مطلقة (مثلاً: https://intlayer.cn/).
     * النطاق يشير إلى اللغة، لذا لا يتم إضافة بادئة لغة إلى المسار.
     * الافتراضي: undefined
     */
    domains: {
      en: "intlayer.org",
      zh: "intlayer.cn",
    },
  },

  /**
   * إعدادات البحث ومعالجة ملفات المحتوى.
   */
  content: {
    /**
     * امتدادات الملفات لفحص القواميس.
     * الافتراضي: ['.content.ts', '.content.js', '.content.json', إلخ]
     */
    fileExtensions: [".content.ts", ".content.js", ".content.json"],

    /**
     * المجلدات التي توجد بها ملفات .content.
     * الافتراضي: ["."]
     */
    contentDir: ["src"],

    /**
     * مجلد كود المصدر.
     * يستخدم لتحسينات البناء وتحويل الكود.
     * الافتراضي: ["."]
     */
    codeDir: ["src"],

    /**
     * الأنماط المستبعدة من الفحص.
     * الافتراضي: ['node_modules', '.intlayer', إلخ]
     */
    excludedPath: ["node_modules"],

    /**
     * ما إذا كان سيتم مراقبة التغييرات وإعادة توليد القواميس أثناء التطوير.
     * الافتراضي: true في وضع التطوير
     */
    watch: true,

    /**
     * أمر لتنسيق ملفات .content المنشأة/المحدثة حديثاً.
     */
    formatCommand: 'npx prettier --write "{{file}}"',
  },

  /**
   * إعدادات المحرر المرئي.
   */
  editor: {
    /**
     * ما إذا كان المحرر المرئي مفعلاً.
     * الافتراضي: false
     */
    enabled: true,

    /**
     * رابط تطبيقك للتحقق من المصدر (origin).
     * الافتراضي: ""
     */
    applicationURL: "http://localhost:3000",

    /**
     * المنفذ لخادم المحرر المحلي.
     * الافتراضي: 8000
     */
    port: 8000,

    /**
     * الرابط العام للمحرر.
     * الافتراضي: "http://localhost:8000"
     */
    editorURL: "http://localhost:8000",

    /**
     * رابط Intlayer CMS.
     * الافتراضي: "https://app.intlayer.org"
     */
    cmsURL: "https://app.intlayer.org",

    /**
     * رابط خادم واجهة برمجة التطبيقات (API) الخلفي.
     * الافتراضي: "https://back.intlayer.org"
     */
    backendURL: "https://back.intlayer.org",

    /**
     * ما إذا كان سيتم تفعيل مزامنة المحتوى في الوقت الفعلي.
     * الافتراضي: false
     */
    liveSync: true,
  },

  /**
   * إعدادات التحليلات (analytics).
   */
  analytics: {
    /**
     * ما إذا كان جمع بيانات التحليلات مفعّلاً (مشاهدات الصفحات، حالات ظهور المحتوى، أحداث A/B).
     * يتطلب تثبيت `@intlayer/analytics` وضبط `editor.clientId` من أجل الإسناد (attribution).
     * الافتراضي: true
     */
    enabled: true,

    /**
     * المللي ثانية بين عمليات الإرسال المجمّعة التلقائية إلى الخادم الخلفي.
     * الافتراضي: 20000
     */
    flushInterval: 20000,

    /**
     * نسبة الجلسات المراد تسجيلها، من 0 (لا شيء) إلى 1 (الكل).
     * الافتراضي: 1
     */
    sampleRate: 1,
  },

  /**
   * إعدادات الترجمة والتوليد باستخدام الذكاء الاصطناعي.
   */
  ai: {
    /**
     * مزود الذكاء الاصطناعي المستخدم.
     * الخيارات: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai', 'lmstudio', 'moonshotai'
     * الافتراضي: 'openai'
     */
    provider: "openai",

    /**
     * النموذج المستخدم من المزود المختار.
     */
    model: "gpt-4o",

    /**
     * مفتاح واجهة برمجة التطبيقات (API key) للمزود.
     */
    apiKey: process.env.OPENAI_API_KEY,

    /**
     * السياق العام لتوجيه الذكاء الاصطناعي عند توليد الترجمات.
     */
    applicationContext: "هذا تطبيق لحجز السفر.",

    /**
     * الرابط الأساسي لواجهة برمجة تطبيقات الذكاء الاصطناعي.
     */
    baseURL: "http://localhost:3000",

    /**
     * تسلسل البيانات
     *
     * الخيارات:
     * - "json": افتراضي، موثوق؛ يستهلك المزيد من الوحدات (tokens).
     * - "toon": حات سريعة، استهلاك أقل للوحدات، أقل استقراراً من JSON.
     *
     * الافتراضي: "json"
     */
    dataSerialization: "json",
  },

  /**
   * إعدادات البناء والتحسين.
   */
  build: {
    /**
     * وضع تنفيذ البناء.
     * - "auto": بناء تلقائي أثناء بناء التطبيق.
     * - "manual": يتطلب أمر بناء صريح.
     * الافتراضي: "auto"
     */
    mode: "auto",

    /**
     * ما إذا كان سيتم تحسين الحزمة الناتجة عن طريق إزالة القواميس غير المستخدمة.
     * الافتراضي: true في الإنتاج
     */
    optimize: true,

    /**
     * ما إذا كان سيتم ضغط القواميس لتقليل حجم الحزمة.
     * الافتراضي: true
     */
    minify: true,

    /**
     * ما إذا كان سيتم حذف المفاتيح غير المستخدمة في القواميس.
     * الافتراضي: true
     */
    prune: true,

    /**
     * تجميع أجزاء القاموس لكل لغة حسب حدود تقسيم الشيفرة التي تستخدمها، بحيث تجلب
     * الصفحة المحمّلة بتكاسل محتواها في طلب واحد.
     * الافتراضي: true
     *
     * ملاحظة:
     * - ينطبق فقط على القواميس التي تستخدم `importMode: 'dynamic'`.
     */
    chunkGrouping: true,

    /**
     * تحميل القاموس مع الجزء الذي يستخدمه، بدلاً من جلبه بعد عرض ذلك الجزء. تُعرض
     * القراءات بشكل متزامن بدلاً من التعليق، لذا لم تعد حالة التحميل تومض أثناء
     * التنقل.
     * الافتراضي: true
     *
     * ملاحظة:
     * - يتم انتظار اللغة المحددة فقط، لذا تنزّل الصفحة اللغة التي تعرضها فحسب.
     */
    dictionariesPreload: true,

    /**
     * صيغة الإخراج لملفات القاموس المولدة.
     * الافتراضي: ['cjs', 'esm']
     */
    outputFormat: ["cjs", "esm"],

    /**
     * ما إذا كان ينبغي للبناء التحقق من أنواع TypeScript.
     * الافتراضي: false
     */
    checkTypes: false,
  },

  /**
   * إعدادات السجل (Logger).
   */
  log: {
    /**
     * مستوى السجل.
     * - "default": تسجيل قياسي.
     * - "verbose": تسجيل تصحيح مفصل.
     * - "disabled": لا يوجد تسجيل.
     * الافتراضي: "default"
     */
    mode: "default",

    /**
     * بادئة لجميع الرسائل في السجل.
     * الافتراضي: "[intlayer]"
     */
    prefix: "[intlayer]",
  },

  /**
   * إعدادات النظام (حالات الاستخدام المتقدمة)
   */
  system: {
    /**
     * المجلد لتخزين القواميس المترجمة.
     */
    dictionariesDir: ".intlayer/dictionary",

    /**
     * المجلد لتوسيع الوحدات (module augmentation).
     */
    moduleAugmentationDir: ".intlayer/types",

    /**
     * المجلد لتخزين القواميس غير المدمجة.
     */
    unmergedDictionariesDir: ".intlayer/unmerged_dictionary",

    /**
     * المجلد لتخزين أنواع القواميس.
     */
    typesDir: ".intlayer/types",

    /**
     * المجلد حيث يتم الاحتفاظ بملفات التطبيق الرئيسية.
     */
    mainDir: ".intlayer/main",

    /**
     * المجلد حيث يتم الاحتفاظ بملفات الإعدادات المحولة برمجياً.
     */
    configDir: ".intlayer/config",

    /**
     * المجلد لملفات التخزين المؤقت (cache).
     */
    cacheDir: ".intlayer/cache",
  },

  /**
   * إعدادات المترجم (حالات الاستخدام المتقدمة)
   */
  compiler: {
    /**
     * ما إذا كان سيتم تفعيل المترجم.
     *
     * - false: تعطيل المترجم.
     * - true: تفعيل المترجم.
     * - "build-only": تخطي المترجم أثناء التطوير لبدء أسرع.
     *
     * الافتراضي: false
     */
    enabled: true,

    /**
     * يحدد المسار لملفات الإخراج. يستبدل `outputDir`.
     *
     * - يتم حل المسارات التي تبدأ بـ `./` بالنسبة لمجلد المكون.
     * - يتم حل المسارات التي تبدأ بـ `/` بالنسبة لمجلد المشروع الأساسي (`baseDir`).
     *
     * - وجود متغير `{{locale}}` في المسار يفعل توليد قواميس منفصلة لكل لغة.
     *
     * مثال:
     * ```ts
     * {
     *   // إنشاء ملفات .content.ts متعددة اللغات بجانب المكون
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // مكافئ عبر سلسلة قالب
     * }
     * ```
     *
     * ```ts
     * {
     *   // إنشاء ملفات JSON مركزية حسب اللغة في مجلد المشروع الأساسي
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // مكافئ عبر سلسلة قالب
     * }
     * ```
     *
     * قائمة المتغيرات:
     *   - `fileName`: اسم الملف.
     *   - `key`: مفتاح المحتوى.
     *   - `locale`: لغة المحتوى.
     *   - `extension`: امتداد الملف.
     *   - `componentFileName`: اسم ملف المكون.
     *   - `componentExtension`: امتداد ملف المكون.
     *   - `format`: صيغة القاموس.
     *   - `componentFormat`: صيغة قاموس المكون.
     *   - `componentDirPath`: المسار إلى مجلد المكون.
     */
    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,

    /**
     * ما إذا كان سيتم حفظ المكونات بعد تحويلها.
     * بهذه الطريقة، يمكن تشغيل المترجم مرة واحدة لتحويل التطبيق ثم إزالته.
     */
    saveComponents: false,

    /**
     * وضع المحتوى فقط في الملف المولد. مفيد لمخرجات بصيغة i18next أو ICU MessageFormat JSON حسب اللغة.
     */
    noMetadata: false,

    /**
     * بادئة لمفتاح القاموس
     */
    dictionaryKeyPrefix: "", // إضافة بادئة اختيارية لمفاتيح القواميس المستخرجة
  },

  /**
   * مخططات مخصصة للتحقق من صحة محتوى القاموس.
   */
  schemas: {
    "my-schema": z.object({
      title: z.string(),
    }),
  },

  /**
   * تكوين القاموس.
   */
  dictionary: {
    /**
     * يتحكم في كيفية استيراد القواميس.
     * - "static": يتم استيرادها بشكل ثابت في وقت البناء.
     * - "dynamic": يتم استيرادها ديناميكيًا باستخدام Suspense.
     * - "fetch": يتم جلبها ديناميكيًا عبر واجهة برمجة تطبيقات المزامنة المباشرة.
     */
    importMode: "static",

    /**
     * تنسيق الرسالة الافتراضي لجميع القواميس في المشروع.
     * - 'intlayer': تنسيق intlayer الأصلي (الافتراضي).
     * - 'icu': تنسيق رسالة ICU.
     * - 'i18next': تنسيق i18next.
     * - 'vue-i18n': تنسيق Vue I18n.
     * - 'po': تنسيق GNU Gettext PO.
     */
    format: "icu",
  },

  /**
   * تكوين الإضافات.
   */
  plugins: [
    syncJSON({
      format: "icu",
      source: ({ locale }) => `./messages/${locale}.json`,
    }),
  ],
};

export default config;

routing: {
  mode: "prefix-no-default", // إستراتيجية احتياطية
  rewrite: nextjsRewrite({
    "/about": {
      en: "/about",
      fr: "/a-propos",
    },
    "/product/[slug]": {
      en: "/product/[slug]",
      fr: "/produit/[slug]",
    },
    "/blog/[category]/[id]": {
      en: "/blog/[category]/[id]",
      fr: "/journal/[category]/[id]",
    },
  }),
}

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: "localStorage",
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: [
      {
        type: "localStorage",
        name: "user-locale",
      },
      {
        type: "cookie",
        name: "user-locale",
        secure: true,
        sameSite: "strict",
        httpOnly: false,
      },
    ],
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "search-params",
    storage: "localStorage",
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "no-prefix",
    storage: {
      type: "sessionStorage",
      name: "app-locale",
    },
    basePath: "/my-app",
  },
};

export default config;

// intlayer.config.ts
import { nextjsRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default", // احتياطي للمسارات غير المعاد كتابتها
    storage: "cookie",
    rewrite: nextjsRewrite({
      "/about": {
        en: "/about",
        fr: "/a-propos",
      },
      "/product/[slug]": {
        en: "/product/[slug]",
        fr: "/produit/[slug]",
      },
      "/blog/[category]/[id]": {
        en: "/blog/[category]/[id]",
        fr: "/journal/[category]/[id]",
      },
    }),
  },
};

export default config;

dictionary: {
  fill: {
    en: "/locales/en/{{key}}.content.json",
    fr: ({ key }) => `/locales/fr/${key}.content.json`,
    es: false,
  },
};