إنشاء:2025-07-27آخر تحديث:2025-07-27

    موجه اللغة

    موجه اللغة هو أداة قوية تساعدك على العمل مع بيانات التدويل في تطبيق Intlayer الخاص بك. يوفر ثلاث وظائف رئيسية لتحويل وتنظيم البيانات الخاصة بكل لغة: localeMap، و localeFlatMap، و localeRecord.

    كيف يعمل موجه اللغة

    يعمل موجه اللغة على كائن LocaleData يحتوي على جميع المعلومات اللازمة حول اللغة:

    type LocaleData = {
      locale: LocalesValues; // رمز اللغة الحالي (مثل 'en'، 'fr')
      defaultLocale: LocalesValues; // رمز اللغة الافتراضية
      isDefault: boolean; // هل هذه هي اللغة الافتراضية
      locales: LocalesValues[]; // مصفوفة بجميع اللغات المتاحة
      urlPrefix: string; // بادئة URL لهذه اللغة (مثل '/fr' أو '')
    };

    تقوم دوال الموجه بإنشاء هذه البيانات تلقائيًا لكل لغة في تكوينك، مع مراعاة:

    • قائمة اللغات التي قمت بتكوينها
    • إعداد اللغة الافتراضية
    • ما إذا كان يجب إضافة بادئة اللغة الافتراضية في عناوين URL

    الوظائف الأساسية

    localeMap

    تحول كل لغة إلى كائن واحد باستخدام دالة موجهة.

    localeMap<T>(
      mapper: (locale: LocaleData) => T,
      locales?: LocalesValues[],
      defaultLocale?: LocalesValues,
      prefixDefault?: boolean
    ): T[]

    مثال: إنشاء كائنات المسارات

    import { localeMap } from "intlayer";
    
    const routes = localeMap((localizedData) => ({
      path: localizedData.urlPrefix,
      name: localizedData.locale,
      isDefault: localizedData.isDefault,
      locales: localizedData.locales,
      defaultLocale: localizedData.defaultLocale,
    }));
    
    // النتيجة:
    // [
    //   { path: '/', name: 'en', isDefault: true, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
    //   { path: '/fr', name: 'fr', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
    //   { path: '/es', name: 'es', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' }
    // ]

    localeFlatMap

    مشابه لـ localeMap، ولكن دالة التحويل تُرجع مصفوفة من الكائنات التي يتم تسويتها إلى مصفوفة واحدة.

    localeFlatMap<T>(
      mapper: (locale: LocaleData) => T[],
      locales?: LocalesValues[],
      defaultLocale?: LocalesValues,
      prefixDefault?: boolean
    ): T[]

    مثال: إنشاء مسارات متعددة لكل لغة

    import { localeFlatMap } from "intlayer";
    
    const routes = localeFlatMap((localizedData) => [
      {
        path: localizedData.urlPrefix,
        name: localizedData.locale,
        isDefault: localizedData.isDefault,
      },
      {
        path: `${localizedData.urlPrefix}/about`,
        name: `${localizedData.locale}-about`,
        isDefault: localizedData.isDefault,
      },
    ]);
    
    // النتيجة:
    // [
    //   { path: '/', name: 'en', isDefault: true },
    //   { path: '/about', name: 'en-about', isDefault: true },
    //   { path: '/fr', name: 'fr', isDefault: false },
    //   { path: '/fr/about', name: 'fr-about', isDefault: false },
    //   { path: '/es', name: 'es', isDefault: false },
    //   { path: '/es/about', name: 'es-about', isDefault: false }
    // ]

    localeRecord

    ينشئ كائن سجل حيث تكون كل لغة مفتاحًا يشير إلى قيمة تم تحويلها بواسطة دالة الماب.

    localeRecord<T>(
      mapper: (locale: LocaleData) => T,
      locales?: Locales[],
      defaultLocale?: Locales,
      prefixDefault?: boolean
    ): Record<Locales, T>

    مثال: تحميل ملفات الترجمة

    import { localeRecord } from "intlayer";
    
    const translations = localeRecord(({ locale }) =>
      require(`./translations/${locale}.json`)
    );
    
    // النتيجة:
    // {
    //   en: { welcome: 'Welcome', hello: 'Hello' },
    //   fr: { welcome: 'Bienvenue', hello: 'Bonjour' },
    //   es: { welcome: 'Bienvenido', hello: 'Hola' }
    // }

    إعداد ماب اللغة

    يستخدم ماب اللغة تلقائيًا تكوين Intlayer الخاص بك، ولكن يمكنك تجاوز الإعدادات الافتراضية بتمرير معلمات:

    استخدام التكوين الافتراضي

    import { localeMap } from "intlayer";
    
    // يستخدم التكوين من intlayer.config.ts
    const routes = localeMap((data) => ({
      path: data.urlPrefix,
      locale: data.locale,
    }));

    تجاوز التكوين

    import { localeMap } from "intlayer";
    
    // تجاوز اللغات واللغة الافتراضية
    const customRoutes = localeMap(
      (data) => ({ path: data.urlPrefix, locale: data.locale }),
      ["en", "fr", "de"], // اللغات المخصصة
      "en", // اللغة الافتراضية المخصصة
      true // إضافة بادئة اللغة الافتراضية في عناوين URL
    );

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

    إنشاء قوائم التنقل

    import { localeMap } from "intlayer";
    
    const navigationItems = localeMap((data) => ({
      label: data.locale.toUpperCase(),
      href: data.urlPrefix || "/",
      isActive: data.isDefault,
      flag: `/flags/${data.locale}.svg`,
    }));

    توليد بيانات خريطة الموقع

    import { localeFlatMap } from "intlayer";
    
    const sitemapUrls = localeFlatMap((data) => [
      {
        url: `${data.urlPrefix}/`,
        lastmod: new Date().toISOString(),
        changefreq: "daily",
        priority: data.isDefault ? 1.0 : 0.8,
      },
      {
        url: `${data.urlPrefix}/about`,
        lastmod: new Date().toISOString(),
        changefreq: "شهريًا",
        priority: data.isDefault ? 0.8 : 0.6,
      },
    ]);

    تحميل الترجمة الديناميكي

    import { localeRecord } from "intlayer";
    
    const translationModules = localeRecord(({ locale }) => ({
      messages: import(`./locales/${locale}/messages.json`),
      validation: import(`./locales/${locale}/validation.json`),
      metadata: {
        locale,
        direction: ["ar", "he", "fa"].includes(locale)
          ? "من اليمين إلى اليسار"
          : "من اليسار إلى اليمين",
      },
    }));

    تكامل التهيئة

    يتكامل موجه اللغات بسلاسة مع تهيئة Intlayer الخاصة بك:

    • اللغات: يستخدم تلقائيًا configuration.internationalization.locales
    • اللغة الافتراضية: يستخدم configuration.internationalization.defaultLocale
    • بادئة عنوان URL: يحترم configuration.middleware.prefixDefault

    هذا يضمن الاتساق عبر تطبيقك ويقلل من تكرار التهيئة.