مترجم Intlayer | استخراج المحتوى الآلي للتدويل

ما هو مترجم Intlayer؟

يعد مترجم Intlayer أداة قوية مصممة لأتمتة عملية التدويل (i18n) في تطبيقاتك. يقوم بفحص شفرة المصدر الخاصة بك (JSX، TSX، Vue، Svelte) بحثًا عن إعلانات المحتوى، ويستخرجها، ويولد تلقائيًا ملفات القاموس اللازمة. يتيح لك هذا الاحتفاظ بالمحتوى بجانب مكوناتك بينما يتولى Intlayer إدارة ومزامنة قواميسك.

لماذا تستخدم مترجم Intlayer؟

• التشغيل الآلي: يلغي الحاجة إلى نسخ ولصق المحتوى يدويًا في القواميس.

• السرعة: استخراج المحتوى المحسّن الذي يضمن بقاء عملية البناء لديك سريعة.

• تجربة المطور: احتفظ بإعلانات المحتوى في مكان استخدامها، مما يحسن سهولة الصيانة.

• الأتمتة: يلغي النسخ واللصق اليدوي للمحتوى في القواميس.
• السرعة: استخراج المحتوى بشكل محسن لضمان بقاء عملية البناء سريعة.
• تجربة المطور: احتفظ بإعلانات المحتوى في المكان الذي تُستخدم فيه، مما يحسن من سهولة الصيانة.
• التحديثات الحية: يدعم استبدال الوحدات الساخنة (HMR) لتلقي ردود فعل فورية أثناء التطوير.

راجع منشور المدونة المترجم مقابل i18n التصريحي لمقارنة أعمق.

لماذا لا تستخدم مترجم Intlayer؟

بينما يوفر المترجم تجربة ممتازة "تعمل مباشرة"، فإنه يقدم أيضًا بعض المقايضات التي يجب أن تكون على دراية بها:

• الغموض الاستدلالي: يجب على المترجم تخمين ما هو المحتوى الموجه للمستخدم مقابل منطق التطبيق (على سبيل المثال، className="active"، رموز الحالة، معرفات المنتجات). في قواعد التعليمات البرمجية المعقدة، يمكن أن يؤدي هذا إلى إيجابيات خاطئة أو سلاسل مفقودة تتطلب تعليقات يدوية واستثناءات.

• الاستخراج الثابت فقط: يعتمد الاستخراج القائم على المترجم على التحليل الثابت. لا يمكن اكتشاف السلاسل التي توجد فقط في وقت التشغيل (رموز أخطاء API، حقول CMS، إلخ) أو ترجمتها بواسطة المترجم وحده، لذلك لا يزال لديك حاجة إلى استراتيجية i18n وقت التشغيل التكميلية.

• استخراج ثابت فقط: يعتمد الاستخراج القائم على المترجم على التحليل الثابت. لا يمكن اكتشاف أو ترجمة السلاسل النصية التي توجد فقط في وقت التشغيل (رموز خطأ API، حقول CMS، إلخ) بواسطة المترجم وحده، لذا تحتاج إلى استراتيجية i18n تشغيلية إضافية.

لمقارنة معمارية أعمق، راجع منشور المدونة المترجم مقابل i18n التصريحي.

كبديل، لأتمتة عملية i18n الخاصة بك مع الحفاظ على السيطرة الكاملة على المحتوى الخاص بك، يوفر Intlayer أيضًا أمر الاستخراج التلقائي intlayer extract (راجع وثائق CLI)، أو أمر Intlayer: extract content to Dictionary من امتداد Intlayer VS Code (راجع وثائق امتداد VS Code).

الاستخدام

The quickest way to wire the compiler in is the interactive setup: run npx intlayer init --interactive and select Compiler. On Vite there is nothing to configure — the compiler is plugged in directly through the intlayerCompiler() plugin. On Next.js the command scaffolds the babel.config.js shown below. The non-interactive intlayer init leaves the compiler setup untouched.

npm install vite-intlayer

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

# لـ Vue
npm install @intlayer/vue-compiler

# لـ Svelte
npm install @intlayer/svelte-compiler

npm install @intlayer/babel

const {
  intlayerExtractBabelPlugin,
  intlayerOptimizeBabelPlugin,
  getExtractPluginOptions,
  getOptimizePluginOptions,
} = require("@intlayer/babel");

module.exports = {
  presets: ["next/babel"],
  plugins: [
    // استخراج المحتوى من المكونات إلى قواميس
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
    // تحسين الاستيراد عن طريق استبدال useIntlayer باستيراد قواميس مباشر
    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
  ],
};

التكوين المخصص

لتخصيص سلوك المترجم، يمكنك تحديث ملف intlayer.config.ts في جذر مشروعك.

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  compiler: {
    /**
     * يشير إلى ما إذا كان يجب تمكين المجمّع.
     * اضبط على 'build-only' لتخطي المجمّع أثناء التطوير وتسريع أوقات التشغيل.
     */
    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: ({ fileName, extension }) => `./${fileName}${extension}`,

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

    /**
     * أدخل المحتوى فقط في الملف الذي تم إنشاؤه. مفيد لإخراج JSON لـ i18next أو ICU MessageFormat لكل لغة.
     *
     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`
     */
    noMetadata: false,

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

export default config;

مرجع تكوين المجمّع

يمكن تكوين الخصائص التالية في كتلة compiler في ملف intlayer.config.ts الخاص بك:

• enabled:

  • النوع: boolean | 'build-only'
  • الافتراضي: true
  • الوصف: يشير إلى ما إذا كان يجب تمكين المجمّع.

• dictionaryKeyPrefix:

  • النوع: string
  • الافتراضي: ''
  • الوصف: بادئة لمفاتيح القواميس المستخرجة.

• transformPattern:

  • النوع: string | string[]
  • الافتراضي: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • الوصف: (مهجور: استخدم build.traversePattern بدلاً من ذلك) أنماط لاجتياز الكود لتحسينه.

• excludePattern:

  • النوع: string | string[]
  • الافتراضي: ['**/node_modules/**']
  • الوصف: (مهجور: استخدم build.traversePattern بدلاً من ذلك) أنماط لاستبعادها من التحسين.

• output:

  • النوع: FilePathPattern
  • الافتراضي: ({ key }) => 'compiler/${key}.content.json'
  • الوصف: يحدد مسار ملفات الإخراج. يستبدل outputDir. يتعامل مع المتغيرات الديناميكية مثل {{locale}} و {{key}} و {{fileName}} و {{extension}} و {{format}} و {{dirPath}} و {{componentFileName}} و {{componentExtension}} و {{componentFormat}}. يمكن تعيينه كسلسلة باستخدام تنسيق 'my/{{var}}/path'، أو كدالة.
  • ملاحظة: يتم حل مسار ./**/* بالنسبة للمكون. يتم حل مسار /**/* بالنسبة لـ baseDir الخاص بـ Intlayer.
  • ملاحظة: إذا تم تعريف اللغة في المسار، سيتم توليد القواميس لكل لغة.
  • مثال: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • النوع: boolean
  • الافتراضي: false
  • الوصف: يشير إلى ما إذا كان سيتم حفظ البيانات الوصفية في الملف. إذا كان صحيحا، فلن يحفظ المجمّع البيانات الوصفية للقواميس (المفتاح، غلاف المحتوى). مفيد لمخرجات JSON i18next أو ICU MessageFormat لكل لغة.
  • ملاحظة: مفيد إذا تم استخدامه مع إضافة loadJSON.
  • مثال: إذا كان true: json { "key": "value" } إذا كان false: json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • النوع: boolean
  • الافتراضي: false
  • الوصف: يشير إلى ما إذا كان يجب حفظ المكونات بعد تحويلها.

ملء الترجمات المفقودة

يوفر Intlayer أداة CLI لمساعدتك في ملء الترجمات المفقودة. يمكنك استخدام أمر intlayer لاختبار وملء الترجمات المفقودة من الكود الخاص بك.

npx intlayer test         # اختبار ما إذا كانت هناك ترجمات مفقودة

npx intlayer fill         # ملء الترجمات المفقودة

الاستخراج

يوفر Intlayer أداة CLI لاستخراج المحتوى من الكود الخاص بك. يمكنك استخدام أمر intlayer extract لاستخراج المحتوى من الكود الخاص بك.

npx intlayer extract

لمزيد من التفاصيل، راجع توثيق CLI