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

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

شاهد تنفيذ الحزمة على GitHub.

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

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

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

البدء

شاهد قالب التطبيق على GitHub.

التثبيت

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

npx intlayer init --interactive

علامة --interactive اختيارية. استخدم intlayer-cli init إذا كنت وكيل ذكاء اصطناعي.

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

npm install intlayer fastify-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,cjs,md,mdx,yaml,yml}).

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

إعداد تطبيق 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({
    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
• vite-intlayer لتطبيقات Vite

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

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... خيارات التكوين الأخرى
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "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.

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

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

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

تكوين Git

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

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

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

الأسئلة الشائعة