المؤلف:
    إنشاء:2026-06-05آخر تحديث:2026-06-05

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

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

    بدلاً من تحميل ملفات JSON ضخمة في صفحاتك، قم بتحميل المحتوى الضروري فقط. يساعدك Intlayer على تقليل حجم bundle والصفحات بنسبة تصل إلى 50%.

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

    Intlayer هو أيضًا الحل الذي يتمتع بـ أنشط تطور في نظام i18n البيئي - يتم إصلاح المشاكل بسرعة، وتصل محولات frameworks جديدة بانتظام، ويتم تحسين API الأساسي بشكل مستمر بناءً على ملاحظات الإنتاج الواقعية.

    يقلل Co-locating المحتوى من السياق المطلوب بواسطة النماذج اللغوية الكبيرة (LLMs). يأتي Intlayer أيضًا مع مجموعة من الأدوات، مثل CLI لاختبار الترجمات المفقودة، LSP، MCP، و مهارات الوكيل، لجعل تجربة المطور (DX) أكثر سلاسة حتى بالنسبة لوكلاء AI.

    استخدم الأتمتة للترجمة في خط أنابيب CI/CD الخاص بك باستخدام LLM من اختيارك بتكلفة موفر AI الخاص بك. يوفر Intlayer أيضًا مترجم لأتمتة استخراج المحتوى، وكذلك منصة ويب لمساعدتك في الترجمة في الخلفية.

    ربط ملفات JSON ضخمة بمكونات قد يؤدي إلى مشاكل الأداء والتفاعل. يحسّن Intlayer تحميل المحتوى الخاص بك في وقت البناء.

    أكثر من مجرد حل i18n، يوفر Intlayer محرر بصري مستضاف على الخادم الخاص بك و CMS كامل لمساعدتك في إدارة محتوى متعدد اللغات في الوقت الفعلي، مما يجعل التعاون مع المترجمين والمحررين وأعضاء الفريق الآخرين سلساً. يمكن تخزين المحتوى محليًا و/أو عن بعد.

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

    نظراً لأن next-i18next يلتف حول react-i18next و i18next تحت الغطاء، هناك استراتيجيتان متكاملتان للترحيل إلى Intlayer:

    1. محول التوافق (موصى به للتطبيقات الموجودة) — قم بتثبيت @intlayer/next-i18next و @intlayer/react-i18next و @intlayer/i18next. تعرض هذه الحزم نفس API تماماً كنظيراتها لكن توكل جميع أعمال الترجمة إلى Intlayer تحت الغطاء. تحتفظ باستدعاءات useTranslation و appWithTranslation و serverSideTranslations الموجودة والتوجيه Pages من Next.js دون تغيير - التغيير الوحيد هو التهيئة.

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

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

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

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

    الخطوات التالية هي الحد الأدنى المطلوب للحصول على تطبيق Next.js Pages Router الموجود يعمل على Intlayer دون تغييرات الكود في الصفحات والمكونات.

    1. تثبيت التبعيات

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

      bash
      npx intlayer-cli init --interactive
      العلم --interactive اختياري. استخدم intlayer-cli init إذا كنت وكيلاً من AI.
      سيكتشف هذا الأمر بيئتك ويثبت الحزم المطلوبة. على سبيل المثال:
      bash
      npm install intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
      يمكنك بأمان الاحتفاظ بـ next-i18next و react-i18next و i18next المثبتة أثناء الترحيل، على الرغم من أنك ستزيلها بمجرد إنشاء بديل.

    2. تكوين Intlayer

      ينشئ أمر intlayer init ملف intlayer.config.ts البداية. قم بتحديثه ليطابق المناطق الموجودة لديك وأشر مكون syncJSON إلى ملفات رسائل next-i18next (عادة داخل public/locales):

      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: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
      location: "public/locales",
    }),
  ],
};

export default config;
      source يعيّن منطقة واسم مساحة (key) إلى مسار ملفها JSON. location يخبر المراقب Intlayer أي مجلد يجب مراقبته للتغييرات. يضمن الخيار format: 'i18next' أن العناصر النائبة يتم تحليلها بشكل صحيح لـ next-i18next.

    3. تحديث إعداد Next.js

      لف إعداد next.config.ts (أو .js) الموجود مع createNextI18nPlugin من @intlayer/next-i18next/plugin. يقوم هذا الغلاف بدمج withIntlayer و حقن بدائل next-i18next / react-i18next / i18next → @intlayer/*، بحيث تتم إعادة توجيه استدعاءات import { useTranslation } from 'next-i18next' الموجودة بشفافية في وقت البناء. لا توجد حاجة لتغييرات ملفات المصدر.

      next.config.ts
      import type { NextConfig } from "next";
import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
// يمكنك إزالة التكوين i18n المستورد من next-i18next.config.js
// import { i18n } from './next-i18next.config';

const withIntlayer = createNextI18nPlugin();

const nextConfig: NextConfig = {
  // يدير Intlayer توجيه i18n في Next.js تحت الغطاء،
  // لذا لا تحتاج إلى تمرير كائن i18n هنا بعد الآن.
};

export default withIntlayer(nextConfig);

      لا تحتاج أكثر إلى next-i18next.config.js. يجمّع Intlayer جميع القواامس في وقت البناء، معالجة كشف locale والتوجيه وتحميل القاموس بسلاسة.

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

    هذا كل ما هو مطلوب للترحيل السريع. تطبيق Next.js الخاص بك يعمل الآن على Intlayer مع الحفاظ على كل استدعاء useTranslation و serverSideTranslations و appWithTranslation سليم.

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

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

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

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

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

      اختياري

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

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

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

    2. تفعيل أتمتة الترجمة المدعومة بـ 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: ({ key, locale }) => `./public/locales/${locale}/${key}.json`,
      location: "public/locales",
    }),
  ],
  ai: {
    apiKey: process.env.OPENAI_API_KEY,
    // provider: "openai",     // الافتراضي
    // model: "gpt-4o-mini",   // الافتراضي
  },
};

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

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

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

    الملف / النمط لماذا لا يكون مطلوباً بعد الآن
    next-i18next.config.js يتعامل Intlayer مع التوجيه وتحميل القاموس والمناطق الافتراضية داخلياً بناءً على intlayer.config.ts.
    next-i18next من package.json تم استبدالها بالكامل بـ @intlayer/next-i18next والبدائل.
    حزم اللغة JSON (public/locales/*.json) حزم JSON مطلوبة فقط إذا كنت تستخدم بعد مكون syncJSON. بمجرد الترحيل إلى ملفات .content.ts يمكنك حذف مجلد JSON.

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

    تكوين TypeScript

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

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

    تكوين Git

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

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

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

    لماذا Intlayer؟