Documentation: t Function in express-intlayer

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

نظرة عامة

تستخدم دالة t لتعريف واسترجاع الترجمات لمجموعة معينة من اللغات. تقوم بتحديد اللغة المناسبة تلقائيًا للرجوع إليها استنادًا إلى إعدادات طلب العميل، مثل رأس Accept-Language. إذا كانت اللغة المفضلة غير متاحة، فإنها تتراجع برشاقة إلى اللغة الافتراضية المحددة في تكوينك.

الميزات الرئيسية

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

توقيع الدالة

t(translations: Record<string, string>): string;

المعلمات

• translations: كائن حيث المفاتيح هي رموز اللغات (مثل en, fr, es-MX) والقيم هي السلاسل المترجمة المقابلة.

القيم المرجعة

• سلسلة تمثل المحتوى باللغة المفضلة للعميل.

تحميل معالج طلبات التدويل

لضمان أن تعمل وظيفة التدويل التي توفرها express-intlayer بشكل صحيح، يجب عليك تحميل وسيط التدويل في بداية تطبيق Express الخاص بك. هذا يمكّن دالة t ويضمن التعامل السليم مع اكتشاف اللغة والترجمة.

إعداد الوسيط المطلوب

import express, { type Express } from "express";
import { intlayer } from "express-intlayer";

const app: Express = express();

// تحميل معالج طلبات التدويل
app.use(intlayer());

موضعه في التطبيق

ضع الوسيط app.use(intlayer()) قبل أي مسارات في تطبيقك لضمان استفادة جميع المسارات من التدويل:

app.use(intlayer());

// تعريف المسارات الخاصة بك بعد تحميل الوسيط
app.get("/", (_req, res) => {
  res.send(
    t({
      en: "Hello, World!",
      fr: "Bonjour le monde!",
      es: "¡Hola, Mundo!",
    })
  );
});

لماذا هذا مطلوب

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

أمثلة على الاستخدام

مثال أساسي

خدمة المحتوى المحلي باللغات المختلفة:

app.get("/", (_req, res) => {
  res.send(
    t({
      en: "Welcome!",
      fr: "Bienvenue!",
      es: "¡Bienvenido!",
    })
  );
});

طلبات العميل:

• سيستلم العميل الذي لديه Accept-Language: fr Bienvenue!.
• سيستلم العميل الذي لديه Accept-Language: es ¡Bienvenido!.
• سيستلم العميل الذي لديه Accept-Language: de Welcome! (اللغة الافتراضية).

معالجة الأخطاء

توفير رسائل الخطأ بعدة لغات:

app.get("/error", (_req, res) => {
  res.status(500).send(
    t({
      en: "An unexpected error occurred.",
      fr: "Une erreur inattendue s'est produite.",
      es: "Ocurrió un error inesperado.",
    })
  );
});

استخدام المتغيرات اللغوية

تحديد الترجمات للمتغيرات الخاصة باللغة:

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

مواضيع متقدمة

آلية التراجع

إذا كانت اللغة المفضلة غير متاحة، ستتراجع دالة t إلى اللغة الافتراضية المحددة في التكوين:

const config = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
};

على سبيل المثال:

• إذا كانت defaultLocale هي Locales.CHINESE وطلب عميل Locales.DUTCH، ستكون الترجمة المرجعة افتراضية إلى قيمة Locales.CHINESE.
• إذا لم يتم تعريف defaultLocale، ستتراجع دالة t إلى قيمة Locales.ENGLISH.

فرض الوضع الصارم

تهيئة دالة t لفرض الالتزام الصارم باللغات المعلنة:

مثال على التكوين:

const config = {
  internationalization: {
    strictMode: "strict", // فرض وضع صارم
  },
};

تكامل TypeScript

تكون دالة t آمنة من حيث النوع عند استخدامها مع TypeScript. قم بتعريف كائن ترجمات آمن من حيث النوع:

import { type LanguageContent } from "express-intlayer";

const translations: LanguageContent<string> = {
  en: "Good morning!",
  fr: "Bonjour!",
  es: "¡Buenos días!",
};

app.get("/morning", (_req, res) => {
  res.send(t(translations));
});

الأخطاء الشائعة واستكشاف الأخطاء

نصائح للاستخدام الفعال

1. مركزة الترجمات: استخدم وحدة مركزية أو ملفات JSON لإدارة الترجمات لتحسين الصيانة.
2. تحقق من الترجمات: تأكد من توفر ترجمة مقابلة لكل متغير لغة لمنع التراجع غير الضروري.
3. التنسيق مع i18n في الواجهة الأمامية: تنسيق مع التدويل في الواجهة الأمامية لتحقيق تجربة مستخدم سلسة عبر التطبيق.
4. قياس الأداء: اختبار أوقات استجابة التطبيق الخاص بك عند إضافة الترجمات لضمان الحد الأدنى من التأثير.

الخاتمة

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