الترحيل من i18next إلى Intlayer

لماذا الترحيل من i18next إلى Intlayer؟

استراتيجيات الترحيل

هناك استراتيجيتان متكاملتان للترحيل من i18next إلى Intlayer:

1. محول التوافق (موصى به للتطبيقات الموجودة) — قم بتثبيت @intlayer/i18next. تكشف هذه الحزمة عن نفس API تماماً من i18next ولكن تفوض كل عمل الترجمة إلى Intlayer تحت الغطاء. تحافظ على استدعاءات i18next.t() و i18next.changeLanguage() و createInstance() الموجودة — التغيير الوحيد هو مسار الاستيراد والتهيئة.

2. الترحيل الكامل — استبدل تدريجياً APIs من i18next بأدوات Intlayer الأصلية ودمج المحتوى في ملفات .content.ts.

يغطي هذا الدليل الاستراتيجية 1 أولاً (محول التوافق drop-in)، ثم يرشدك عبر الترحيل الكامل الاختياري.

جدول المحتويات

الترحيل السريع

الخطوات التالية هي الحد الأدنى المطلوب لتشغيل تطبيق i18next الموجود على Intlayer بدون تغيير الكود.

1. 1

   تثبيت التبعيات

   قم بتثبيت حزم Intlayer الأساسية ومحول التوافق:

   bash

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   npx intlayer-cli init --interactive

   العلم --interactive اختياري. استخدم intlayer-cli init إذا كنت وكيل ذكي.

   سيكتشف هذا الأمر بيئتك وسيثبت الحزم المطلوبة. على سبيل المثال:

   bash

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   npm install intlayer @intlayer/i18next @intlayer/sync-json-plugin

   يمكنك الاحتفاظ بـ i18next مثبتاً — يستخدم محول التوافق كـ devDependency / peerDependency لأنواع TypeScript.

2. 2

   تكوين Intlayer

   ينشئ أمر intlayer init ملف intlayer.config.ts بدء. حدثّه ليطابق البيئات المحلية الموجودة لديك وأشر إلى مكوّن syncJSON في ملفات الرسائل الخاصة بك:

   intlayer.config.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // أضف جميع البيئات المحلية الموجودة لديك هنا
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // يطابق صيغة ملاصقات i18next: {{name}}
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   source يعيّن بيئة محلية إلى مسار ملف JSON الخاص بها. location يخبر مراقب Intlayer أي مجلد للبحث عن التغييرات. يضمن الخيار format: 'i18next' أن الملاصقات مثل {{name}} يتم تحليلها بشكل صحيح.

3. 3

   تحديث أسماء Bundler المستعارة (اختياري)

   إذا كنت تستخدم bundler (Vite, Webpack, esbuild)، يمكنك حقن اسم مستعار للملف حتى يتم حل import ... from 'i18next' تلقائياً إلى @intlayer/i18next. يزيل الحاجة لتغيير الاستيرادات يدويياً في قاعدة الكود الخاصة بك.

   لـ Vite:

   vite.config.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { defineConfig } from "vite";
   import i18nextVitePlugin from "@intlayer/i18next/plugin";
   
   export default defineConfig({
     plugins: [i18nextVitePlugin()],
   });

   i18nextVitePlugin() يغلف مكوّن intlayer() من vite-intlayer ويضيف اسم مستعار i18next → @intlayer/i18next لك. يجمّع المكوّن العادي intlayer() من vite-intlayer القواامس ولكن لا يضيف هذا الاسم المستعار — يمكنك حينها إعادة تسمية الاستيرادات إلى @intlayer/i18next يدويياً (انظر الخطوة التالية).

هذا كل شيء للترحيل السريع. يعمل التطبيق الخاص بك الآن على Intlayer مع الاحتفاظ بكل استيراد API وـ i18next كما هي.

الترحيل الكامل

الخطوات أدناه اختيارية ويمكن إنجازها بشكل تدريجي. تفتح مجموعة ميزات Intlayer الكاملة: محرر مرئي، CMS، ملفات محتوى مكتوبة، ترجمة مدفوعة بالذكاء الاصطناعي، والمزيد.

1. 4

   إعادة تسمية الاستيراد الصريحة (اختياري)

   اختياري

   إذا كنت تفضل جعل التبعية صريحة في ملفات المصدر الخاصة بك، أو إذا لم تكن تستخدم مكوّن bundler لتحويل الاستيرادات، يمكنك إعادة تسمية الاستيرادات يدويياً:

   اظهار جميع محتويات الجدول

   اظهار جميع محتويات الجدول

   افتح الجدول في نافذة منبثقة لعرض جميع محتويات البيانات بوضوح

   قبل	بعد
   import i18next from 'i18next'	import i18next from '@intlayer/i18next'
   import { createInstance } from 'i18next'	import { createInstance } from '@intlayer/i18next'
   import { t } from 'i18next'	import { t } from '@intlayer/i18next'

   هذه بدائل drop-in — لا تغييرات في توقيعات الدالة أو الحجج أو أنواع الإرجاع مطلوبة.

2. 5

   تفعيل أتمتة الترجمة المدفوعة بالذكاء الاصطناعي

   اختياري

   بمجرد توصيل Intlayer، استخدم CLI الخاص به لملء الترجمات المفقودة تلقائياً:

   bash

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   # اختبر الترجمات المفقودة (أضف إلى CI)npx intlayer test# ملء الترجمات المفقودة بـ AInpx intlayer fill

   أضف تكوين AI إلى intlayer.config.ts:

   intlayer.config.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // افتراضي
       // model: "gpt-4o-mini",   // افتراضي
     },
   };
   
   export default config;

   انظر وثائق Intlayer CLI لجميع الخيارات المتاحة.

ما يمكنك حذفه بعد الترحيل

بمجرد وضع محول التوافق، يمكن إزالة نموذج i18next التالي:

عندما تكون جاهزاً للمضي أبعد، يكتشف Intlayer تلقائياً جميع ملفات .content.ts و .content.json في أي مكان في قاعدة الكود الخاصة بك (افتراضياً، في أي مكان داخل ./src). يمكنك وضع ملف my-component.content.ts بجانب منطقك مباشرة وسيلتقطه Intlayer في وقت البناء بدون تكوين إضافي — لا استيرادات، لا تسجيل، لا حاجة لملف فهرس مركزي. هذا يجعل دمج الترجمات بدون احتكاك تماماً.

تكوين TypeScript

يستخدم Intlayer module augmentation لتوفير intellisense TypeScript الكامل لمفاتيح الترجمة الخاصة بك. تأكد من أن tsconfig.json الخاص بك يتضمن الأنواع المُنتجة تلقائياً:

{  // ... تكوينات TypeScript الموجودة لديك  "include": [    // ... تكوينات TypeScript الموجودة لديك    ".intlayer/**/*.ts", // تضمين الأنواع المُنتجة تلقائياً  ],}

تكوين Git

أضف مجلد Intlayer المُنتج إلى .gitignore الخاص بك:

# تجاهل الملفات المُنتجة بواسطة Intlayer.intlayer

اذهب أبعد

• محرر مرئي — إدارة الترجمات بصرياً في متصفحك: محرر Intlayer المرئي
• CMS — خارج الخدمة وإدارة المحتوى بعداً: CMS Intlayer
• VS Code Extension — الحصول على الإكمال التلقائي واكتشاف أخطاء الترجمة في الوقت الفعلي: ملحق Intlayer VS Code
• مرجع CLI — قائمة كاملة بأوامر CLI: Intlayer CLI