البدء في التدويل (i18n) باستخدام Intlayer و Express

express-intlayer هو وسيط قوي للتدويل (i18n) لتطبيقات Express، مصمم لجعل خدماتك الخلفية متاحة عالميًا من خلال توفير استجابات محلية بناءً على تفضيلات العميل.

لماذا تدويل الخلفية؟

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

حالات استخدام عملية

• عرض أخطاء الخلفية بلغة المستخدم: عند حدوث خطأ، عرض الرسائل بلغة المستخدم الأصلية يحسن الفهم ويقلل من الإحباط. هذا مفيد بشكل خاص للرسائل الديناميكية التي قد تظهر في مكونات الواجهة الأمامية مثل التوست أو النوافذ المنبثقة.

• استرجاع المحتوى متعدد اللغات: بالنسبة للتطبيقات التي تسحب المحتوى من قاعدة بيانات، يضمن التدويل أنه يمكنك تقديم هذا المحتوى بلغات متعددة. هذا أمر حيوي للمنصات مثل مواقع التجارة الإلكترونية أو أنظمة إدارة المحتوى التي تحتاج إلى عرض أوصاف المنتجات والمقالات والمحتويات الأخرى باللغة المفضلة للمستخدم.

• إرسال رسائل بريد إلكتروني متعددة اللغات: سواء كانت رسائل بريد إلكتروني معاملاتية، حملات تسويقية، أو إشعارات، فإن إرسال رسائل البريد الإلكتروني بلغة المستلم يمكن أن يزيد بشكل كبير من التفاعل والفعالية.

• إشعارات دفع متعددة اللغات: بالنسبة لتطبيقات الهاتف المحمول، إرسال إشعارات الدفع بلغة المستخدم المفضلة يمكن أن يعزز التفاعل والاحتفاظ. هذه اللمسة الشخصية يمكن أن تجعل الإشعارات تبدو أكثر ملاءمة وقابلة للتنفيذ.

• اتصالات أخرى: أي شكل من أشكال الاتصال من الخلفية، مثل رسائل SMS، تنبيهات النظام، أو تحديثات واجهة المستخدم، يستفيد من أن يكون بلغة المستخدم، مما يضمن الوضوح ويعزز تجربة المستخدم بشكل عام. من خلال تدويل الخلفية، لا يحترم تطبيقك الاختلافات الثقافية فحسب، بل يتماشى أيضًا بشكل أفضل مع احتياجات السوق العالمية، مما يجعله خطوة رئيسية في توسيع خدماتك عالميًا.

البدء

التثبيت

لبدء استخدام express-intlayer، قم بتثبيت الحزمة باستخدام npm:

npm install intlayer express-intlayer

الإعداد

قم بتكوين إعدادات التدويل عن طريق إنشاء ملف intlayer.config.ts في جذر مشروعك:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH_MEXICO,      Locales.SPANISH_SPAIN,    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

إعلان المحتوى الخاص بك

قم بإنشاء وإدارة إعلانات المحتوى الخاصة بك لتخزين الترجمات:

import { t, type Dictionary } from "intlayer";const indexContent = {  key: "index",  content: {    exampleOfContent: t({      en: "Example of returned content in English",      fr: "Exemple de contenu renvoyé en français",      "es-ES": "Ejemplo de contenido devuelto en español (España)",      "es-MX": "Ejemplo de contenido devuelto en español (México)",    }),  },} satisfies Dictionary;export default indexContent;

يمكن تعريف إعلانات المحتوى الخاصة بك في أي مكان داخل تطبيقك طالما تم تضمينها في دليل contentDir (افتراضيًا، ./src). ويجب أن تطابق امتداد ملف إعلان المحتوى (افتراضيًا، .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

لمزيد من التفاصيل، راجع توثيق إعلان المحتوى.

إعداد تطبيق Express

قم بإعداد تطبيق Express الخاص بك لاستخدام express-intlayer:

import express, { type Express } from "express";import { intlayer, t, getDictionary, getIntlayer } from "express-intlayer";import dictionaryExample from "./index.content";const app: Express = express();// تحميل معالج طلبات التدويلapp.use(intlayer());// المساراتapp.get("/t_example", (_req, res) => {  res.send(    t({      ar: "مثال على المحتوى المُعاد باللغة العربية",      en: "Example of returned content in English",      fr: "Exemple de contenu renvoyé en français",      "es-ES": "Ejemplo de contenido devuelto en español (España)",      "es-MX": "Ejemplo de contenido devuelto en español (México)",    })  );});app.get("/getIntlayer_example", (_req, res) => {  res.send(getIntlayer("index").exampleOfContent);});app.get("/getDictionary_example", (_req, res) => {  res.send(getDictionary(dictionaryExample).exampleOfContent);});// بدء الخادمapp.listen(3000, () => console.log(`Listening on port 3000`));

التوافق

express-intlayer متوافق تمامًا مع:

• react-intlayer لتطبيقات React
• next-intlayer لتطبيقات Next.js
• vite-intlayer لتطبيقات Vite يعمل أيضًا بسلاسة مع أي حل للتدويل عبر بيئات مختلفة، بما في ذلك المتصفحات وطلبات API. يمكنك تخصيص الوسيط لاكتشاف اللغة من خلال الرؤوس أو ملفات تعريف الارتباط:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... خيارات تكوين أخرى  middleware: {    headerName: "my-locale-header",    cookieName: "my-locale-cookie",  },};export default config;

بشكل افتراضي، سيقوم express-intlayer بتفسير رأس Accept-Language لتحديد اللغة المفضلة للعميل.

لمزيد من المعلومات حول التهيئة والمواضيع المتقدمة، قم بزيارة التوثيق.

تهيئة TypeScript

يستفيد express-intlayer من القدرات القوية لـ TypeScript لتعزيز عملية التدويل. يضمن النوع الثابت في TypeScript أن يتم تضمين كل مفتاح ترجمة، مما يقلل من خطر فقدان الترجمات ويحسن من سهولة الصيانة.

تأكد من تضمين الأنواع التي تم إنشاؤها تلقائيًا (افتراضيًا في ./types/intlayer.d.ts) في ملف tsconfig.json الخاص بك.

{  // ... Your existing TypeScript configurations  "include": [    // ... Your existing TypeScript configurations    ".intlayer/**/*.ts", // تضمين الأنواع التي تم إنشاؤها تلقائيًا  ],}

امتداد VS Code

لتحسين تجربة التطوير الخاصة بك مع Intlayer، يمكنك تثبيت امتداد Intlayer الرسمي لـ VS Code.

التثبيت من سوق VS Code

يوفر هذا الامتداد:

• الإكمال التلقائي لمفاتيح الترجمة.
• الكشف الفوري عن الأخطاء للترجمات المفقودة.
• معاينات داخلية للمحتوى المترجم.
• إجراءات سريعة لإنشاء وتحديث الترجمات بسهولة.

لمزيد من التفاصيل حول كيفية استخدام الامتداد، راجع توثيق امتداد Intlayer لـ VS Code.

يوصى بتجاهل الملفات التي يتم إنشاؤها بواسطة Intlayer. هذا يسمح لك بتجنب إضافتها إلى مستودع Git الخاص بك.

امتداد VS Code

لتحسين تجربة التطوير الخاصة بك مع Intlayer، يمكنك تثبيت امتداد Intlayer الرسمي لـ VS Code.

التثبيت من سوق VS Code

يوفر هذا الامتداد:

• الإكمال التلقائي لمفاتيح الترجمة.
• كشف الأخطاء في الوقت الحقيقي للترجمات المفقودة.
• معاينات داخلية للمحتوى المترجم.
• إجراءات سريعة لإنشاء الترجمات وتحديثها بسهولة.

لمزيد من التفاصيل حول كيفية استخدام الامتداد، راجع توثيق امتداد Intlayer لـ VS Code.

إعدادات Git

يوصى بتجاهل الملفات التي يتم إنشاؤها بواسطة Intlayer. هذا يسمح لك بتجنب إضافتها إلى مستودع Git الخاص بك.

للقيام بذلك، يمكنك إضافة التعليمات التالية إلى ملف .gitignore الخاص بك:

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

تاريخ الوثيقة

• 5.5.10 - 2025-06-29: بداية التاريخ