Intlayer v9 الجديد - ما الجديد؟

مرحبًا بكم في Intlayer v9! يمثل هذا الإصدار الرئيسي علامة فارقة ضخمة في تبسيط مسار الترحيل إلى Intlayer من خلال حزم محولات التوافق (Compat Adapter Packages) لمكتبات i18n الرئيسية (react-i18next, next-intl, vue-i18n, إلخ) ويضيف دعمًا لهياكل المحتوى الغنية: المجموعات (Collections)، المتغيرات (Variants)، والسجلات الديناميكية (Dynamic Records).

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

حزم محولات التوافق (Compat Adapter Packages)

أصبح الترحيل إلى Intlayer من مكتبات i18n الشهيرة أسهل من أي وقت مضى. لقد أنشأنا خمس حزم توافق تعرض نفس واجهات برمجة التطبيقات العامة (public APIs) تمامًا مثل مكتبات i18n القياسية ولكنها تفوض جميع أعمال الترجمة إلى Intlayer في وقت التشغيل (runtime).

عرض نفس واجهة برمجة التطبيقات العامة (Public API) مع كتابة صارمة (Strict Typing)

باستبدال عمليات الاستيراد (imports)، تحصل على جميع مزايا Intlayer (بما في ذلك أمان النوع في وقت التجميع (compile-time type safety) مقابل قواميسك الفعلية) بأقل تغييرات في الكود:

• @intlayer/i18next
• @intlayer/react-i18next
• @intlayer/next-intl
• @intlayer/next-i18next
• @intlayer/vue-i18n

على سبيل المثال، قم ببساطة بتغيير:

import { useTranslation } from "react-i18next";

إلى:

import { useTranslation } from "@intlayer/react-i18next";

ستكون مفاتيحك الآن مكتوبة بشكل صارم (strictly typed) مقابل قواميس Intlayer الخاصة بك، مما يوفر إكمالًا تلقائيًا كاملاً للمسار النقطي (dot-path auto-completion) في بيئة التطوير المتكاملة (IDE) الخاصة بك!

إضافات اسم مستعار للمجمّع (Bundler Alias Plugins) (Vite, Next.js, Turbopack)

للسماح بالترحيل دون إعادة كتابة جميع عبارات الاستيراد (import statements) يدويًا، تتضمن كل حزمة محول توافق (compat adapter package) إضافة مجمّع مخصصة (custom bundler plugin) (Vite أو Next.js) ضمن المسار الفرعي /plugin.

تعيد هذه الإضافات تلقائيًا كتابة عمليات الاستيراد الموجودة (مثل react-i18next أو next-intl) إلى مكافئاتها @intlayer/* في وقت البناء (build time).

مثال Next.js (Webpack / Turbopack)

بدلاً من withIntlayer، قم بتغليف إعدادات Next.js الخاصة بك باستخدام إضافة التوافق (compat plugin):

import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";import type { NextConfig } from "next";const withIntlayer = createNextI18nPlugin();const nextConfig: NextConfig = {};export default withIntlayer(nextConfig);

مثال Vite (React, Vue, Solid, Svelte)

import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";export default defineConfig({  plugins: [vueI18nVitePlugin()],});

محلل وقت التشغيل المشترك (Mutualized Runtime Resolver)

توجه جميع محولات التوافق (compat adapters) الآن حل الترجمة من خلال محلل وقت تشغيل واحد ومحسن للغاية: @intlayer/core/messageFormat.

• رسالة الاستيفاء (Interpolate Message): تحل {{var}} القياسية (مسافات بيضاء ومسارات نقطية)، وسيطات ICU المنسقة ({v, number, percent} إلخ)، وقوالب {var} المجردة.
• محلل عقدة الرسالة (Message Node Resolver): يحل العقد المتداخلة: insert()، plural() (قواعد الجمع CLDR)، enu() (التعداد)، gender()، علامات HTML، المصفوفات، وعقد الوظائف القابلة للاستدعاء.
• محلل العلامات المرمزة (Tokenized Tag Parser): يدعم علامات XML/HTML المضمنة والعلامات المرقمة (مثل <1>children</1>) لتشغيل عرض النص الغني (rich-text rendering) بشكل جاهز.

مواصفات الميزة: المجموعات (Collections)، المتغيرات (Variants) والسجلات الديناميكية (Dynamic Records)

يتوسع Intlayer v9 إلى ما هو أبعد من كائنات المفتاح-القيمة الثابتة، مما يسمح للقواميس بالإعلان عن هياكل تخطيط ديناميكية مكتوبة بالكامل من البداية إلى النهاية.

1. المجموعات (Collections)

حدد قائمة من العناصر المرتبة التي يديرها نظام إدارة المحتوى (CMS) (مثل الأسئلة الشائعة، المنتجات، أو قوائم المدونات):

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  content: [    {      question: t({        ar: "ما هو Intlayer؟",        en: "What is Intlayer?",        fr: "Qu'est-ce qu'Intlayer ?",      }),      answer: t({        ar: "مجموعة أدوات i18n.",        en: "An i18n toolkit.",        fr: "Une boîte أدوات i18n.",      }),    },  ],} satisfies Dictionary;

الاستخدام:

// جلب جميع العناصرconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// جلب عنصر واحد حسب الفهرسconst faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }

2. المتغيرات (Variants)

قدم اختبارات A/B، رؤوس صفحات موسمية، علامات ميزات (feature flags)، أو صفحات هبوط مخصصة:

import { t, type Dictionary } from "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ ar: "مرحباً", en: "Welcome", fr: "Bienvenue" }),    black_friday: t({      ar: "تسوق الآن",      en: "Shop now",      fr: "Acheter maintenant",    }),  },} satisfies Dictionary;

الاستخدام:

const banner = useIntlayer("hero-banner", { variant: "black_friday" });

3. السجلات الديناميكية (Dynamic Records)

حدد القواميس التي يتم تحميل إدخالاتها ديناميكيًا في وقت التشغيل (runtime) عبر معرفات الاستعلام (query IDs):

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  meta: {    id: "prod_123",    category: "books",  },  content: {    title: t({ ar: "كود نظيف", en: "Clean Code", fr: "Code Propre" }),  },} satisfies Dictionary;

الاستخدام:

// يجلب العنصر المطلوب فقط ديناميكيًا (يتطلب Suspense)const product = useIntlayer("product-copy", {  id: "prod_123",  category: "books",});

التحميل الديناميكي وتحسينات حجم الحزمة (Bundle Size Optimizations)

للحفاظ على أحجام الحزم (bundles) صغيرة للغاية، يدعم Intlayer v9 التحميل الكسول الديناميكي (dynamic lazy loading).

في إعداداتك، اضبط importMode على 'dynamic' أو 'fetch':

export default {  dictionary: {    importMode: "dynamic", // "static" | "dynamic" | "fetch"  },};

في وقت البناء (build time)، يقوم @intlayer/swc و@intlayer/babel بمسح ملفاتك واستبدال استدعاءات useIntlayer / getIntlayer بـ wrappers قابلة للإزالة (tree-shakeable wrappers) (useDictionary / useDictionaryDynamic). يتم تحميل المحتوى المطلوب فقط للعنصر المحدد في المجموعة (collection item)، أو المتغير (variant)، أو اللغة (locale)، مما يمنع حزمة الإنتاج (production bundle) الخاصة بك من احتواء ترجمات غير مستخدمة.

ملاحظات الترحيل من الإصدار 8

إذا كنت تقوم بالترقية من الإصدار 8، لاحظ أن الإصدار 9 لا يتضمن تغييرات جذرية (breaking changes). ولكن إليك التغييرات الرئيسية:

• اللغات واللهجات (Locales & Dialects): إذا كنت تستخدم تبعيات i18n خارجية، أضف إضافات محول التوافق (compat adapter plugins) الخاصة بها في إعداداتك أو إعداد المجمّع (bundler setup) لإعادة كتابة عمليات الاستيراد (imports) تلقائيًا.
• المحددات المخصصة (Custom Selectors): عند استدعاء useIntlayer، تم حجز المعامل الثاني الآن لكائن خيارات يحتوي على { locale, item, variant, id }. إذا كنت قد مررت سابقًا سلسلة لغة (locale string) مباشرة، فلا يزال بإمكانك القيام بذلك، ولكن يوصى باستخدام كائن الخيارات للاختيارات المتقدمة.

روابط مفيدة

• دليل حزم محولات التوافق (Compat Adapter Packages Guide)
• القواميس الديناميكية - المجموعات (Collections)، المتغيرات (Variants) والسجلات الديناميكية (Dynamic Records)
• مرجع الإعدادات (Configuration Reference)