ترجمة موقع الويب الخاص بخادم Fastify باستخدام Intlayer | التدويل (i18n)

fastify-intlayer هو ملحق (plugin) قوي للتدويل (i18n) لتطبيقات Fastify، مصمم لجعل خدمات الـ backend الخاصة بك متاحة عالميًا من خلال تقديم استجابات محلية حسب تفضيلات العميل.

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

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

fastify-intlayer هو مكون إضافي قوي للتدويل (i18n) لتطبيقات Fastify، مصمم لجعل خدمات backend الخاصة بك متاحة عالميًا من خلال تقديم استجابات مَحَلّية بناءً على تفضيلات العميل.

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

• عرض أخطاء الخادم بلغة المستخدم: عندما يحدث خطأ، فإن عرض الرسائل بلغة المستخدم الأم يحسّن الفهم ويقلل الإحباط. هذا مفيد بشكل خاص للرسائل الديناميكية للأخطاء التي قد تُعرض في مكونات الواجهة الأمامية مثل toasts أو modals.
• استرجاع محتوى متعدد اللغات: بالنسبة للتطبيقات التي تجلب المحتوى من قاعدة بيانات، يضمن التدويل أنه يمكنك تقديم هذا المحتوى بعدة لغات. هذا أمر حاسم لمنصات مثل مواقع e-commerce أو أنظمة إدارة المحتوى التي تحتاج إلى عرض أوصاف المنتجات والمقالات ومحتويات أخرى باللغة التي يفضلها المستخدم.
• إرسال رسائل بريد إلكتروني متعددة اللغات: سواء كانت transactional emails أو حملات تسويقية أو notifications، فإن إرسال الرسائل البريدية بلغة المستلم يمكن أن يزيد بشكل كبير من التفاعل والفعالية.
• الإشعارات المتعددة اللغات (Multilingual Push Notifications): بالنسبة لتطبيقات الجوال، إرسال إشعارات الدفع بلغة مفضلة لدى المستخدم يمكن أن يعزز التفاعل والاحتفاظ بالمستخدمين. تضيف هذه اللمسة الشخصية شعورًا بأن الإشعارات ذات صلة وقابلة للتنفيذ.
• وسائل اتصال أخرى: أي شكل من أشكال الاتصال من الـ backend، مثل رسائل SMS أو تنبيهات النظام أو تحديثات واجهة المستخدم، يستفيد من تقديمه بلغة المستخدم، مما يضمن الوضوح ويعزز تجربة المستخدم العامة.

من خلال تدويل الـ backend، لا يحترم تطبيقك الفروق الثقافية فحسب، بل يتماشى أيضًا بشكل أفضل مع احتياجات السوق العالمية، مما يجعله خطوة أساسية لتوسيع نطاق خدماتك عالميًا.

البدء

التثبيت

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

npm install intlayer fastify-intlayernpx intlayer init

الإعداد

قم بتكوين إعدادات التدويل بإنشاء ملف 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({      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)",    }),  },} satisfies Dictionary;export default indexContent;

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

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

إعداد تطبيق Fastify

أعد إعداد تطبيق Fastify لاستخدام fastify-intlayer:

import Fastify from "fastify";import { intlayer, t, getDictionary, getIntlayer } from "fastify-intlayer";import dictionaryExample from "./index.content";const fastify = Fastify({ logger: true });// تحميل إضافة التدويلawait fastify.register(intlayer);// المساراتfastify.get("/t_example", async (_req, reply) => {  return 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)",  });});fastify.get("/getIntlayer_example", async (_req, reply) => {  return getIntlayer("index").exampleOfContent;});fastify.get("/getDictionary_example", async (_req, reply) => {  return getDictionary(dictionaryExample).exampleOfContent;});// بدء الخادمconst start = async () => {  try {    await fastify.listen({ port: 3000 });  } catch (err) {    fastify.log.error(err);    process.exit(1);  }};start();

التوافق

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

• react-intlayer لتطبيقات React

• next-intlayer لتطبيقات Next.js

• react-intlayer لتطبيقات React
• next-intlayer لتطبيقات Next.js
• vite-intlayer لتطبيقات Vite

كما يعمل بسلاسة مع أي حل للتدويل عبر بيئات متعددة، بما في ذلك المتصفحات وطلبات API. يمكنك تخصيص الـ middleware لاكتشاف اللغة عبر الرؤوس أو الكوكيز:

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

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

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

تكوين TypeScript

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

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

{  // ... تكوينات TypeScript الحالية الخاصة بك  "include": [    // ... تكوينات TypeScript الحالية الخاصة بك    ".intlayer/**/*.ts", // تضمين الأنواع المولدة تلقائياً  ],}

امتداد VS Code

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

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

يقدّم هذا الامتداد:

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

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

تكوين Git

يوصى بتجاهل الملفات التي يولّدها Intlayer. يتيح ذلك تجنّب عمل commit لها في مستودع Git الخاص بك.

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

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