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

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

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

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

1. محول التوافق (موصى به للتطبيقات الموجودة) — قم بتثبيت @intlayer/react-i18next (لمكونات React) و/أو @intlayer/i18next (لمثيل i18n الأساسي). تعرض هذه الحزم نفس API تماماً كـ react-i18next / i18next لكنها توكل جميع أعمال الترجمة إلى Intlayer تحت الغطاء. تحتفظ باستدعاءات useTranslation و Trans و withTranslation و i18next.t() الموجودة - التغيير الوحيد هو مسار الاستيراد.

2. الترحيل الكامل — استبدل تدريجياً APIs من react-i18next بـ hooks Intlayer الأصلية (useIntlayer, IntlayerProvider) و ضع المحتوى في ملفات .content.ts بجانب مكوناتك.

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

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

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

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

1. 1

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npx intlayer-cli init --interactive

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

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

   يمكنك الاحتفاظ بـ react-i18next و i18next المثبتة - تستخدم محولات التوافق كـ devDependencies / peerDependencies اختياري لأنواع TypeScript. لا تحتاج إلى تغيير أي أقران package.json.

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({
         // يطابق بناء جملة العنصر النائب من react-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

   إضافة مكون Intlayer إلى Bundler الخاص بك

   لف إعداد bundler الموجود لديك بمكون التوافق. يقوم بدمج مكون Intlayer الأساسي، ويربط مراقبة المحتوى، و - بشكل حاسم - يحقن بدائل module بحيث تتم إعادة توجيه استدعاءات import … from 'react-i18next' (و 'i18next') الموجودة بشفافية إلى @intlayer/react-i18next / @intlayer/i18next في وقت البناء. لا توجد حاجة لتغييرات ملفات المصدر.

   لـ Vite:

   vite.config.ts

   نسخ المحتوى

   نسخ الكود

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

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

   reactI18nextVitePlugin() يلتف مكون intlayer() من vite-intlayer ويضيف بدائل react-i18next / i18next. استخدام مكون intlayer() البسيط من vite-intlayer يجمّع القواميس لكن لا يضيف تلك البدائل - ستقوم بعد ذلك بإعادة تسمية الاستيرادات إلى @intlayer/* يدويًا (انظر الخطوة 4).

   لـ Next.js:

   إذا كنت تستخدم next-i18next (تكامل Pages Router)، قم بتثبيت @intlayer/next-i18next و next-intlayer:

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install @intlayer/next-i18next next-intlayer

   ثم أضف مكون التوافق إلى next.config.ts (يحقن بدائل next-i18next / react-i18next / i18next):

   next.config.ts

   نسخ المحتوى

   نسخ الكود

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

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     /* الخيارات الخاصة بك */
   };
   
   export default withIntlayer(nextConfig);

   لا تحتاج أكثر إلى i18next.init() أو bootstrap موفر يدوي. يجمّع Intlayer جميع القواامس في وقت البناء، لذا لا توجد خطوة تحميل وقت التشغيل. يتعامل موفر المستعار مع التهيئة لك.

هذا كل ما هو مطلوب للترحيل السريع. تطبيقك يعمل الآن على Intlayer مع الحفاظ على كل استيراد واجهة برمجية من react-i18next.

مفاتيح ترجمة مكتوبة - تلقائي. بمجرد أن يجمّع Intlayer القواامس، يتم كتابة useTranslation و getFixedT مقابل المحتوى الفعلي. يتم إكمال المفاتيح تلقائياً في محرر IDE ومسارات غير صحيحة تسبب أخطاء TypeScript في وقت البناء - لا يلزم إعداد إضافي.

tsx

نسخ المحتوى

نسخ الكود

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

// 'about' هو مفتاح قاموس مسجل → t() يقبل فقط نقاط منقوطة صحيحةconst { t } = useTranslation("about");t("counter.label"); // ✓ مكتملt("does.not.exist"); // ✗ خطأ TypeScript// من جانب الخادم (مثيل i18next)const tAbout = i18n.getFixedT(null, "about");tAbout("counter.label"); // ✓ مكتوب

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

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

1. 4

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

   اختياري

   تتعامل مكونات Intlayer بالفعل مع البدائل على مستوى bundler. إذا كنت تفضل جعل التبعية صريحة في ملفات المصدر، يمكنك إعادة تسمية الاستيرادات يدويًا:

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

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

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

   قبل	بعد
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'
   import { Trans } from 'react-i18next'	import { Trans } from '@intlayer/react-i18next'
   import { withTranslation } from 'react-i18next'	import { withTranslation } from '@intlayer/react-i18next'
   import { I18nextProvider } from 'react-i18next'	import { I18nextProvider } from '@intlayer/react-i18next'
   import { initReactI18next } from 'react-i18next'	import { initReactI18next } from '@intlayer/react-i18next'
   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'

   لـ Next.js (next-i18next):

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

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

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

   قبل	بعد
   import { serverSideTranslations } from 'next-i18next/serverSideTranslations'	import { serverSideTranslations } from '@intlayer/next-i18next'
   import { appWithTranslation } from 'next-i18next'	import { appWithTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'next-i18next'	import { useTranslation } from '@intlayer/next-i18next'

2. 5

   تفعيل أتمتة الترجمة المدعومة بـ AI

   اختياري

   بمجرد توصيل 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 لجميع الخيارات المتاحة.

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

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

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

تكوين TypeScript

يستخدم Intlayer تعديل module لتوفير intellisense TypeScript الكامل لمفاتيح الترجمة. تأكد من أن tsconfig.json يتضمن الأنواع التي يتم إنشاؤها تلقائياً:

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

تكوين Git

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

# تجاهل الملفات التي يتم إنشاؤها بواسطة Intlayer.intlayer

اذهب إلى ما هو أبعد

• محرر بصري — إدارة الترجمات بشكل مرئي في المتصفح: محرر Intlayer البصري
• CMS — تحويل إلى خارجي وإدارة المحتوى من بعيد: Intlayer CMS
• VS Code Extension — احصل على إكمال تلقائي واكتشاف خطأ ترجمة فوري: ملحق Intlayer VS Code
• مرجع CLI — قائمة كاملة بأوامر CLI: Intlayer CLI
• Intlayer مع React — دليل الإعداد الكامل لـ React: intlayerwithvite+react.md
• Intlayer مع Next.js — دليل الإعداد الكامل لـ Next.js: intlayerwithnextjs_16.md