الترحيل من next-intl إلى Intlayer

لماذا الترحيل من next-intl إلى Intlayer؟

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

الأسلوب الموصى به للتطبيقات الموجودة هو محول التوافق: قم بتثبيت @intlayer/next-intl، الذي يعرض نفس API تماماً كـ next-intl لكن يوكل جميع أعمال الترجمة إلى Intlayer تحت الغطاء.

تحتفظ باستدعاءات useTranslations و getTranslations و NextIntlClientProvider الموجودة - التغيير الوحيد هو مسار الاستيراد. لا يلزم إعادة بناء توقيعات الاستدعاء أو أشكال props أو بنية المكون.

بمرور الوقت، يمكنك بشكل اختياري ترحيل ملفات فردية إلى صيغة Intlayer الأكثر ثراءً .content.ts لفتح محرر بصري و CMS والنطاق المحتوى لكل مكون - لكن هذه الخطوة اختيارية تماماً ويمكن القيام بها بشكل تدريجي.

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

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

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

1. 1

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

   قم بتثبيت حزم Intlayer الأساسية ومحول التوافق @intlayer/next-intl:

   bash

   نسخ المحتوى

   نسخ الكود

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

   npx intlayer-cli init --interactive

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin

   احتفظ بـ next-intl مثبتاً - لا يزال مطلوباً للتوجيه عبر URL (createNavigation، createMiddleware، Link، redirect، usePathname، useRouter). محول التوافق لا يستبدل طبقة التوجيه.

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({
         // يطابق بناء جملة العنصر النائب من next-intl: {name}, {count, plural, ...}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   export default config;

   source يعيّن منطقة إلى مسار ملفها JSON. location يخبر المراقب Intlayer أي مجلد يجب مراقبته للتغييرات. يضمن الخيار format: 'icu' أن العناصر النائبة ICU مثل {name} و {count, plural, one {# item} other {# items}} يتم تحليلها بشكل صحيح.

   للحصول على قائمة كاملة بخيارات التكوين، راجع وثائق التكوين.

3. 3

   إضافة مكون Intlayer إلى Next.js

   لف إعداد Next.js الموجود لديك مع createNextIntlPlugin من @intlayer/next-intl/plugin. يقوم هذا الغلاف بدمج withIntlayer و تسجيل بدائل next-intl → @intlayer/next-intl لك:

   next.config.ts

   نسخ المحتوى

   نسخ الكود

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

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* خيارات التكوين الموجودة */
   };
   
   export default withIntlayer(nextConfig);

   createNextIntlPlugin() يلتف withIntlayer، ويكتشف تلقائياً Webpack أو Turbopack، ويربط مراقبة المحتوى وترجمة القاموس، و - بشكل حاسم - يحقن بدائل module بحيث تتم إعادة توجيه استدعاءات import … from 'next-intl' الموجودة بشفافية إلى @intlayer/next-intl في وقت البناء. إدخال التوجيه next-intl/routing يترك يشير إلى الحزمة الحقيقية. لا توجد حاجة لتغييرات ملفات المصدر.

   تفضل withIntlayer البسيط من next-intlayer/server؟ سيجمّع قواامسك، لكنه لا يضيف بدائل next-intl - ستضطر بعد ذلك إلى إعادة تسمية الاستيرادات إلى @intlayer/next-intl يدويًا (انظر الخطوة 4).

   لا تحتاج أكثر إلى getRequestConfig أو loadMessages. مع next-intl، كان عليك كتابة ملف src/i18n.ts يحمل حزم رسائل JSON على كل طلب عبر getRequestConfig. يجمّع Intlayer جميع القواامس في وقت البناء، لذا لا توجد خطوة تحميل وقت التشغيل. يمكنك حذف هذا الملف بالكامل (أو الاحتفاظ بأجزاء التوجيه فقط إذا كنت تستخدم createNavigation).

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

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

tsx

نسخ المحتوى

نسخ الكود

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

// مكون العميل - 'about' هو مفتاح قاموس مسجلconst t = useTranslations("about");t("counter.label"); // ✓ مكتملt("does.not.exist"); // ✗ خطأ TypeScript// مكون الخادمconst t = await getTranslations("about");t("counter.label"); // ✓ مكتوب

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

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

1. 4

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

   اختياري

   غلاف createNextIntlPlugin() يتعامل بالفعل مع بديل next-intl → @intlayer/next-intl على مستوى bundler. إذا كنت تفضل جعل التبعية صريحة في ملفات المصدر (واستخدام مكون withIntlayer البسيط بدلاً من ذلك)، يمكنك إعادة تسمية الاستيرادات يدويًا:

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

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

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

   قبل	بعد
   import { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   احفظ دائماً استيرادات التوجيه من next-intl الحقيقية - محول التوافق لا يستبدل طبقة التوجيه عبر URL:

   ts

   نسخ المحتوى

   نسخ الكود

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

   // ✅ احفظ هذه دائماً من `next-intl` الحقيقيةimport { createNavigation } from "next-intl/routing";import { createMiddleware } from "next-intl/server";import { defineRouting } from "next-intl/routing";

   بدلاً من ذلك، يمكنك استخدام defineRouting من @intlayer/next-intl/routing والذي يدمج إعداد locale من intlayer.config.ts تلقائياً.

2. 5

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

   اختياري

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

   bash

   نسخ المحتوى

   نسخ الكود

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

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

   أضف OPENAI_API_KEY (أو مفتاح موفر مفضل) إلى ملف .env الخاص بك، ثم قم بتوسيع 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: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // الافتراضي
       // model: "gpt-4o-mini",   // الافتراضي
     },
   };
   
   export default config;

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

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

بمجرد وضع @intlayer/next-intl، يمكن إزالة الكود النموذجي التالي من next-intl:

عندما تكون جاهزاً للمضي قدماً، يكتشف Intlayer تلقائياً جميع ملفات .content.ts و .content.json في أي مكان في codebase (افتراضياً، في أي مكان داخل ./src). يمكنك وضع ملف about.content.ts بجوار about/page.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 مع Next.js — دليل الإعداد الكامل لـ Next.js: intlayerwithnextjs_16.md