توثيق مكوّن intlayer لـ Elysia

يقوم المكوّن intlayer لـ Elysia باكتشاف الـ locale الخاص بالمستخدم ويحقن كائن intlayer في سياق المسار (route context). كما يتيح استخدام دوال الترجمة العامة ضمن سياق الطلب.

الاستخدام

import { Elysia } from "elysia";
import { intlayer } from "elysia-intlayer";

const app = new Elysia().use(intlayer()).get("/", ({ intlayer }) =>
  intlayer!.t({
    ar: "مرحبًا",
    en: "Hello",
    fr: "Bonjour",
    es: "Hola",
  })
);

تسجّل الإضافة سياقها عبر derive عام، والذي يعطيه Elysia النوع Partial<{ intlayer: IntlayerContext }>. تكون القيمة موجودة دائماً وقت التشغيل للمسارات المسجَّلة بعد .use(intlayer())، لذا استخدم تأكيد عدم الفراغ (intlayer!.t)، أو التسلسل الاختياري، لإرضاء TypeScript في الوضع strict.

نفس الدوال المساعدة متاحة كصادرات مستقلة، بحيث يمكنك استدعاؤها دون تفكيك سياق المسار:

import { Elysia } from "elysia";
import { intlayer, t } from "elysia-intlayer";

const app = new Elysia().use(intlayer()).get("/", () =>
  t({
    ar: "مرحبًا",
    en: "Hello",
    fr: "Bonjour",
    es: "Hola",
  })
);

الوصف

يقوم المكوّن الإضافي بالمهام التالية:

1. كشف الـ locale: يقرأ الـ locale الذي حدده العميل صراحةً من التخزين (كوكي، هيدر)، ثم يعود إلى الـ locale المتفاوض عليه من هيدر Accept-Language.
2. الحقن في السياق: تضيف خاصية intlayer إلى سياق المسار في Elysia (انظر جدول سياق المسار أدناه).
3. تجهيز القواميس: تستدعي prepareIntlayer عند إنشاء الإضافة، بحيث تُبنى القواميس عند إقلاع التطبيق.

سياق المسار

عند استدعاء الدوال المساعدة المستقلة خارج طلب يعالجه المكوّن، تعود إلى الـ locale الافتراضي المُعد.

ترتيب تحديد اللغة

بشكل افتراضي، تحلّ الإضافة اللغة بالترتيب التالي:

1. كوكي INTLAYER_LOCALE.
2. ترويسة x-intlayer-locale.
3. التفاوض عبر ترويسة Accept-Language.
4. قيمة defaultLocale المُعدّة.

# تم التفاوض عليها من `Accept-Language`
curl -H "Accept-Language: fr" http://localhost:3000/
# Bonjour

# للكوكي أولوية على `Accept-Language`
curl -H "Accept-Language: fr" -H "Cookie: INTLAYER_LOCALE=es" http://localhost:3000/
# Hola

# للترويسة أولوية على `Accept-Language`
curl -H "Accept-Language: fr" -H "x-intlayer-locale: es" http://localhost:3000/
# Hola

الإعداد

يقرأ المكوّن ملف intlayer.config.ts الخاص بك. يمكنك تخصيص الكوكي والهيدر المستخدمين لكشف الـ locale:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

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

وثائق ذات صلة