Documentation: دالة getIntlayer في intlayer

الوصف

تقوم دالة getIntlayer باختيار قاموس واحد من خلال مفتاحه وتعيد محتواه المُفسَّر للغة محددة. وهي النظير المستقل عن الإطار (framework-agnostic) للربط useIntlayer: نفس المحتوى، نفس المحددات، لكنها قابلة للاستخدام في أي مكان لا يتوفر فيه سياق React، نصوص Node، دوال الخادم، محملات المسارات، منشئو البيانات الوصفية، معالجات Express/Fastify، الاختبارات.

تقرأ القواميس التي تم إنشاؤها بواسطة Intlayer في .intlayer/، لذا فإن وسيط key له نوع ويتم إكمال سيارته تلقائياً من إعلانات المحتوى الخاصة بك، والكائن المُعاد له نوع كامل حتى كل ورقة.

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

• مفاتيح قاموس مكتوبة ومحتوى مُعاد مكتوب
• تفسير كل عقدة محتوى (t()، enu()، cond()، insert()، nest()، md()، html()، file()، gender())
• قبول لغة أو كائن محدد (مجموعات، متغيرات)
• يتم حفظ النتائج في الذاكرة لكل key + locale + selector
• الرجوع إلى وكيل آمن في وضع التطوير عندما يكون القاموس مفقوداً، بدلاً من توقف البرنامج

توقيع الدالة

getIntlayer(
  key: DictionaryKeys,                        // مطلوب
  localeOrSelector?: LocalesValues | DictionarySelector, // اختياري
  plugins?: Plugins[]                         // اختياري
): DeepTransformContent<...>

المعاملات

• key: DictionaryKeys

  • الوصف: مفتاح القاموس المراد قراءته، كما هو معلّن في ملفات المحتوى الخاصة بك.
  • النوع: DictionaryKeys، اتحاد كل مفاتيح القاموس المعلنة.
  • مطلوب: نعم

• localeOrSelector: LocalesValues | DictionarySelector

  • الوصف: اللغة المراد تفسير المحتوى بها، أو كائن محدد لـ القواميس الديناميكية.
    • 'fr': لغة
    • { item: 2 }: عنصر مجموعة (حذف item للحصول على كل عنصر كمصفوفة)
    • { variant: 'black-friday' }: متغير مسمى (حذف للحصول على المتغير default)
    • { variant: { id: 'prod_abc', userId: '123' } }: متغير منظم
    • أي محدد يمكنه أن يحمل لغة: { item: 2, locale: 'fr' }
  • النوع: LocalesValues | DictionarySelector
  • مطلوب: لا (اختياري). عند حذفها، راجع بدون locale.

• plugins: Plugins[]

  • الوصف: محولات عقدة مخصصة تحل محل مكونات المُفسّر الأساسية. للاستخدام المتقدم فقط؛ حذفها للحفاظ على السلوك الافتراضي.
  • النوع: Plugins[]
  • مطلوب: لا (اختياري)

العودة

• النوع: محتوى القاموس المُفسَّر، مُكتَّب من تصريحك.
• الوصف: كائن عادي يعكس حقل content من قاموسك، حيث تم حل كل عقدة Intlayer إلى قيمتها النهائية للغة المطلوبة.

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

الاستخدام الأساسي

import { t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: t({
      ar: "مرحبا",
      en: "Hello",
      fr: "Bonjour",
    }),
  },
} satisfies Dictionary;

export default appContent;

import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app", "fr"); // "Bonjour"

بدون locale

عند عدم تمرير أي locale، لا تنتقل getIntlayer مباشرة إلى locale الافتراضية. بل تحل بالترتيب:

1. locale الطلب الحالي، على الخادم، عندما يعالجه تكامل من Intlayer: الـ middlewares express-intlayer وfastify-intlayer وhono-intlayer وadonis-intlayer وelysia-intlayer، والـ middlewares remix-intlayer وastro-intlayer، وIntlayerProvider / setLocale في React Server Components. يُحل كل طلب من ملفات cookies والـ headers الخاصة به، لذا لا يتشارك المستخدمون المتزامنون الـ locale أبدًا.
2. locale المخزنة في المتصفح (cookie، localStorage، sessionStorage)، وهي التي يحفظها مبدّل اللغة.
3. defaultLocale المعلنة في الإعدادات.

import { getIntlayer } from "intlayer";

const { title } = getIntlayer("app"); // locale الطلب، وإلا المخزنة، وإلا الافتراضية

ينطبق الحل نفسه على getDictionary، وعلى الاستدعاءات التي تعيد كتابتها إضافات البناء، وعلى useIntlayer / useDictionaryDynamic عند عرضها خارج provider. الـ locale الممررة صراحةً لها الأولوية دائمًا.

getIntlayer ليست تفاعلية: بعد تغيير الـ locale، استدعها من جديد لقراءة الـ locale الجديدة. في صفحة معروضة على الخادم، يعرض الاستدعاء خارج أي provider الـ locale الافتراضية على الخادم والـ locale المخزنة في المتصفح، مما قد يسبب hydration mismatch. في هذه الحالة، أضف provider الخاص بإطار عملك أو مرّر الـ locale.

داخل معالج الخادم

import { getIntlayer, getLocale } from "intlayer";

export const greetingHandler = async (request: Request) => {
  const locale = await getLocale({
    getHeader: (name) => request.headers.get(name) ?? undefined,
  });

  const { title } = getIntlayer("app", locale);

  return Response.json({ title });
};

مع محدد (المجموعات والمتغيرات)

import { getIntlayer } from "intlayer";

// عنصر مجموعة واحد
const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });

// كل عنصر من المجموعة، كمصفوفة مرتبة
const allPosts = getIntlayer("blog-post", { locale: "fr" });

// متغير مسمى
const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });

ملاحظات السلوك

التخزين المؤقت

تُحفظ النتائج في ذاكرة تخزين مؤقت على مستوى الوحدة مفهرسة بـ key + locale + selector. استدعاء getIntlayer("app", "fr") بشكل متكرر يفسر القاموس مرة واحدة فقط ويعيد نفس الكائن بعد ذلك.

القواميیس المفقودة

أثناء التطوير، طلب مفتاح لا توجد له قاموس مُنشأ يسجل تحذيراً مرة واحدة ويعيد بروكسي آمن للعودة: قراءة content.title تعطي السلسلة "app.title" بدلاً من رفع خطأ. هذا يحافظ على الصفحة قابلة للاستخدام بينما يتم إصلاح الإعلان المفقود. قم بتشغيل بناء Intlayer (أو خادم التطوير) حتى يتم إنشاء القاموس.

حجم الحزمة

يقرأ getIntlayer القاموس المدمج الذي يحتوي على كل لغة. في حزم العميل، تعيد ملحقات البناء كتابة الاستدعاء بحيث يتم شحن المحتوى المطلوب فقط. عندما تقرأ المحتوى خارج التصيير (البيانات الوصفية، المحملات، وظائف الخادم) وتريد تحميل لغة واحدة حسب الطلب، استخدم getIntlayerAsync بدلاً من ذلك.

الدوال ذات الصلة

TypeScript

function getIntlayer<
  const T extends DictionaryKeys,
  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
>(
  key: T,
  localeOrSelector?: A,
  plugins?: Plugins[]
): DeepTransformContent<
  DictionaryRegistryResult<T, A>,
  IInterpreterPluginState,
  ExtractSelectorLocale<A>
>;