ضبط إعادة كتابة الترجمات التدويلية (i18n)

استخدِم عمليات إعادة الكتابة المتوافقة مع المعايير الدولية ("عمليات إعادة الكتابة المتوافقة مع المعايير الدولية") لعرض محتوى مختلف استنادًا إلى بلد المستخدم أو لغته المفضّلة. في ما يلي بعض الأمثلة على الإعدادات التي يمكنك ضبطها:

• عرض المحتوى نفسه باللغة الفرنسية لكل المستخدمين الذين يفضّلون اللغة الفرنسية (بغض النظر عن البلد)
  مثال: صفحة رئيسية تتضمّن نصًا باللغة الفرنسية

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

• عرض المحتوى نفسه لكل المستخدمين الكنديين (بغض النظر عن اللغة المفضّلة لديهم)
  مثال: صفحة رئيسية تستخدم اللغة "الافتراضية" لموقعك الإلكتروني ولكنها تتضمّن ميزة خاصة بكندا (مثل تصميم مرتبط بمناسبة)

• عرض محتوى بالفرنسية الكندية للمستخدمين الكنديين الذين يفضّلون اللغة الفرنسية
  مثال: صفحة رئيسية تتضمّن عبارات بالفرنسية الكندية وميزة خاصة بكندا (مثل تصميم مرتبط بمناسبة)

تحدّد Firebase Hosting بلد المستخدم من عنوان IP الخاص به، وتحدّد إعدادات اللغة المفضّلة للمستخدم من عنوان Accept-Language (الذي يحدّده متصفّح الويب تلقائيًا عادةً).

إعداد عمليات إعادة الكتابة المتوافقة مع النشر على نطاق عالمي

لإعداد عمليات إعادة الكتابة المتوافقة مع تدويل المحتوى لموقعك الإلكتروني Hosting، عليك إنشاء دليل "محتوى متوافق مع تدويل المحتوى" لجميع المحتوى المترجم، ثم إضافة السمة i18n إلى ملف firebase.json للإشارة إلى دليل "المحتوى المتوافق مع تدويل المحتوى" الجديد.

في ما يلي الخطوات المفصّلة التي يجب اتّباعها:

1. في مجلد public ضمن دليل التطبيق المحلي، أنشئ مجلدًا منفصلاً لـ "المحتوى المتوافق مع معايير اللغة"، ثم أنشئ مجلدات فرعية لكل تركيبة من اللغة والبلد التي يتيحها موقعك الإلكتروني.

   في كل مجلد فرعي، أضِف المحتوى الخاص بهذا المزيج، مثل الصفحات الرئيسية ذات الطابع الاحتفالي أو صفحات 404 الخاصة بلغة معيّنة.

   في ما يلي مثال على دليل "محتوى متعدد اللغات" باسم localized-files:

   public/
       index.html  // your site's default homepage
       404.html  // your site's custom 404 page
   
       localized-files/
           ALL_ca/
               index.html
           es_ALL/
               index.html
               404.html
           fr/
               index.html
               404.html
           fr_ca/
               index.html

   عرض الطلبات المطابقة لمحتوى كل مجلد فرعي

   public/
       // matches requests that aren't specified by your "i18n content" subfolders
       // example: display your homepage in the "default" language for your site with no country-specific features
       index.html  // your site's default homepage
       404.html  // your site's custom 404 page
   
       localized-files/
   
           // matches requests from Canada with any language preference
           // example: display your homepage in the "default" language for your site with a Canada-specific feature
           ALL_ca/
               index.html
   
           // matches requests from any country with a language preference of `es` or `es-foo`
           // example: display your homepage in Spanish with no country-specific features
           es_ALL/
               index.html
               404.html  // your site's custom 404 page in Spanish
   
           // matches requests from any country with a language preference of `fr` or `fr-foo`
           // example: display your homepage in Standard French with no country-specific features
           fr/
               index.html
               404.html  // your site's custom 404 page in French
   
           // matches requests from Canada with a language preference of `fr` or `fr-foo`
           // example: display your homepage in Canadian French and/or with a Canada-specific feature
           fr_ca/
               index.html

   يحتوي الدليل localized-files/ على مجلدات فرعية منفصلة لكل مجموعة من اللغات والبلدان التي يتيحها موقعك الإلكتروني. يجب أن يتّبع نمط التسمية لكل مجلد فرعي أحد التنسيقَين التاليَين:

   • languageCode_countryCode: يحتوي على محتوى مخصّص للمستخدمين الذين لديهم إعدادات اللغة المفضّلة ورمز البلد

   • ‫languageCode: يحتوي على محتوى مخصّص للمستخدمين الذين يفضّلون هذه اللغة، ولكن المحتوى ليس خاصًا ببلد معيّن، أي أنّه يعادل languageCode_ALL

   راجِع القسم الفرعي رموز البلدان واللغات أدناه للحصول على مزيد من التفاصيل حول هذه الرموز. يمكنك استخدام قيمة ALL (مع مراعاة حالة الأحرف) للإشارة إلى أي بلد (مثل es_ALL/) أو أي لغة (مثل ALL_ca/).

   لا يشترط أن تتضمّن الملفات في مجلد فرعي ملفات مماثلة في الدليل public أو في مجلدات فرعية أخرى. يمكنك إنشاء محتوى مخصّص بالكامل للغة و/أو بلد معيّن.

2. أضِف السمة i18n إلى ملف firebase.json وحدِّد الدليل الذي يحتوي على "محتوى متعدد اللغات". لنتابع مثالنا:

   // firebase.json
   
   "hosting": {
   
     "public": "public",
   
     "ignore": [
       "firebase.json",
       "**/.*",
       "**/node_modules/**"
     ],
   
     "i18n": {
       "root": "/localized-files"  // directory that contains your "i18n content"
     }
   
     ...
   }

   يجب أن يكون الدليل المحدّد لـ root هو اسم الدليل الذي يحتوي على كل المجلدات الفرعية الخاصة بـ "المحتوى المتوافق مع اللغات المختلفة". إذا وضعت جميع المجلدات الفرعية الخاصة بـ "المحتوى المتوافق مع معايير التدويل" في جذر دليل public، استخدِم / كقيمة root. الشرطات المائلة في بداية ونهاية قيمة root هي قيم اختيارية.

3. انشر "محتوى i18n" وإعداداتك على موقعك الإلكتروني Hosting.

يمكنك اختبار إعداداتك باستخدام عمليات إلغاء ملفات تعريف الارتباط.

رموز البلدان واللغات

عند تسمية المجلدات الفرعية الخاصة بـ "المحتوى المتوافق مع عدة لغات"، يجب استخدام أحرف صغيرة لكل من رموز البلدان واللغات. يمكنك استخدام قيمة ALL (حساسة لحالة الأحرف) للإشارة إلى أي بلد (مثل es_ALL/) أو أي لغة (مثل ALL_ca/).

تحصل Hosting على رمز البلد من عنوان IP الخاص بالمستخدم. رموز البلدان هي رموز مكوّنة من حرفَين وفقًا لمعيار ISO 3166-1 alpha-2.

يتم الحصول على رموز اللغة من عنوان الطلب Accept-Language الخاص بالمستخدم (يتم عادةً ضبطها تلقائيًا بواسطة متصفح الويب). وهي رموز ISO 639-1. يُرجى مراعاة ما يلي عند استخدام رموز اللغات:

• عندما يبحث Hosting عن "محتوى متعدد اللغات" لعرضه، يرتب اللغات استنادًا إلى قيم الجودة في عنوان Accept-Language.

• يزيل Hosting أي علامات فرعية خاصة بالمنطقة والبلد في رأس Accept-Language، وبالتالي لا يمكن أن يحتوي رمز اللغة في اسم مجلد فرعي "خاص بالمحتوى المتوافق مع معايير اللغة العالمية" على هذه العلامات الفرعية. على سبيل المثال، لا يمكنك استخدام es-419 أو es-US كرمز لغة في اسم مجلد فرعي، ولكن يمكنك استخدام es.

  إذا كنت تريد عرض محتوى خاص بمنطقة أو بلد معيّن، يمكنك إنشاء مجلدات فرعية تحتوي على المحتوى الخاص باللغة والبلد اللذين تريد إتاحتهما.

  عرض أمثلة لدعم محتوى خاص بمنطقة أو بلد معيّنَين

  عرض محتوى إسباني مناسب لإسبانيا بدلاً من أي بلد آخر (محاكاة سلوك es-419)

  في هذا المثال، سيتلقّى طلب من إسبانيا يتضمّن الإعداد المفضّل للغة es أو es-es أو حتى es-419 محتوًى من المجلد الفرعي es_es/ لأنّ Hosting يتعامل مع جميع رموز اللغة هذه على أنّها es.

  سيتلقّى المستخدمون في الولايات المتحدة أو المكسيك أو أي بلد آخر يفضّلون اللغة es-419 المحتوى من المجلد الفرعي es_ALL/ لأنّ Hosting يتعامل مع es-419 على أنّه es.

  public/
      // matches requests that aren't specified by your "i18n content" subfolders
      index.html  // the site's default homepage
  
      localized-files/
  
          // matches requests from Spain with a language preference of `es` or `es-foo`
          es_es/
              index.html
  
          // matches requests from any other country with a language preference of `es` or `es-foo`
          es_ALL/
              index.html

  عرض محتوى باللغة الإسبانية ينطبق على بلدان محدّدة

  في هذا المثال، سيتلقّى طلب من المكسيك مع إعدادات اللغة المفضّلة es-419 محتوًى من المجلد الفرعي es_mx/ لأنّ Hosting يتعامل مع رمز اللغة es-419 على أنّه es.

  في المقابل، إذا كان الطلب واردًا من الولايات المتحدة مع تحديد اللغة المفضّلة على أنّها es-419، سيتم عرض المحتوى من المجلد الفرعي es_ALL/ لأنّ Hosting يتعامل مع es-419 على أنّه es ولا يتوفّر مجلد فرعي es_us/.

  public/
      // matches requests that aren't specified by your "i18n content" subfolders
      index.html  // the site's default homepage
  
      localized-files/
  
          // matches requests from Argentina with a language preference of `es` or `es-foo` (mimics behavior of `es-ar` header tag)
          es_ar/
              index.html
  
          // matches requests from Spain with a language preference of `es` or `es-foo` (mimics behavior of `es-es` header tag)
          es_es/
              index.html
  
          // matches requests from Mexico with a language preference of `es` or `es-foo` (mimics behavior of `es-mx` header tag)
          es_mx/
              index.html
  
          // matches requests from any other country with a language preference of `es` or `es-foo` (mimics behavior of `es-419` header tag)
          es_ALL/
              index.html

ترتيب الأولوية لـ "المحتوى المتوافق مع اللغات المختلفة"

في حال إعداد عمليات إعادة كتابة i18n، يعرض Hosting المحتوى استنادًا إلى ترتيب الأولوية التالي:

1. مساحات الأسماء المحجوزة التي تبدأ بشريحة مسار /__/*

2. عمليات إعادة التوجيه التي تم إعدادها

3. المحتوى الثابت الذي يتضمّن تطابقًا تامًا

   1. رمز اللغة + رمز البلد (مثلاً، المحتوى من fr_ca/)
      يتبع الترتيب قيم الجودة لكل لغة في العنوان Accept-Language للطلب.

   2. رمز البلد فقط (مثلاً، محتوى من ALL_ca/)

   3. رمز اللغة فقط (على سبيل المثال، المحتوى من fr/ أو es_ALL/)
      يتبع الترتيب قيم الجودة لكل لغة في عنوان Accept-Language للطلب.

   4. المحتوى الثابت الذي يتطابق تمامًا مع المحتوى "الافتراضي"
      هذا هو المحتوى الذي يقع خارج دليل "محتوى i18n"، مثل المحتوى الموجود في الجذر من الدليل public.

4. عمليات إعادة الكتابة التي تم ضبطها

5. التعامل مع أخطاء 404

   1. صفحات i18n 404
      تتبع هذه الصفحات ترتيب الأولوية نفسه المذكور أعلاه للمحتوى الثابت الذي يتطابق تمامًا مع طلب البحث.

   2. صفحة 404 مخصّصة

   3. صفحة 404 التلقائية (مقدَّمة من Firebase)

مثال على ترتيب الأولوية

لنواصل مثالنا من الأعلى. سنستخدم دليل الأمثلة نفسه وطلب مثال.

• مثال على دليل مشروع محلي يتضمّن دليل "محتوى تدويل" (يُسمى localized-files)

  public/
      index.html  // your site's default homepage
      404.html  // your site's custom 404 page
  
      localized-files/
          ALL_ca/
              index.html
          es_ALL/
              index.html
              404.html
          fr/
              index.html
              404.html
          fr_ca/
              index.html

• مثال على معلومات الطلب

  • رموز اللغة: fr وen (الفرنسية ثم الإنجليزية)
    يتم ترتيب رموز اللغة استنادًا إلى قيم الجودة في العنوان Accept-Language.

  • رمز البلد: ca (كندا)

وفقًا لترتيب الأولوية للمطابقة التامة وقيم الجودة الخاصة بتفضيلات اللغة، سيبحث Hosting في الدلائل عن صفحة مطلوبة بالترتيب التالي.

1. public/localized-files/fr_ca/

2. public/localized-files/en_ca/

3. public/localized-files/ALL_ca/

4. public/localized-files/fr_ALL/

5. public/localized-files/fr/

6. public/localized-files/en_ALL/

7. public/localized-files/en/

8. public/

9. التعامل مع أخطاء 404

أي صفحة سيتم عرضها للمستخدم؟

• الصفحة المطلوبة: index.html

  الإجابة

  index.html من المجلد الفرعي fr_ca/

  بما أنّ Hosting يبحث في المجلد الفرعي fr_ca/ أولاً، سيجد المطابقة التامة لعبارة index.html في هذا المجلد الفرعي.

• الصفحة المطلوبة: awesome-page.html

  الإجابة

  404.html من المجلد الفرعي fr/

  يبحث Hosting أولاً في الدليل بأكمله (بما في ذلك جميع المجلدات الفرعية ومجلد الجذر التي تحتوي على "محتوى متعدد اللغات") حسب ترتيب الأولوية عن تطابق تام، ولكن لا يوجد تطابق تام مع awesome-page.html.

  لذلك، ستبدأ Hosting في معالجة الخطأ 404، والتي تتّبع ترتيب الأولوية نفسه المتعلّق بتدويل المواقع (i18n) كما هو الحال مع عمليات البحث التي تستخدم المطابقة التامة. المجلد الفرعي fr/ هو أول مجلد فرعي يتم البحث فيه ويحتوي على صفحة 404.

يُرجى ملاحظة ما يلي بشأن عملية البحث عن دليل "محتوى i18n" وعرضه:

• لا يحتوي الدليل localized-files/ في الواقع على المجلدات الفرعية en_ca/ أو en_ALL/ أو en/، لذا سيتخطى Hosting قائمة الأولوية إلى أن يعثر على مجلد فرعي مطابق لمجموعة اللغة والبلد الخاصة بالطلب.

• على الرغم من أنّ الدليل localized-files/ يحتوي على مجلد فرعي es_ALL/، لا يتضمّن الطلب الوارد في المثال أعلاه رمز اللغة es أو es-foo، وبالتالي لن يبحث Hosting عن "محتوى متعدد اللغات" يطابق es.

• المجلدات الفرعية التي تحمل الاسمَين fr/ وfr_ALL/ متطابقة من منظور الإعدادات المفضّلة للبلد واللغة لدى المستخدم. ومع ذلك، إذا كان كلا المجلّدين الفرعيين متوفّرَين، ستعرض Hosting محتوى fr_ALL/ قبل محتوى fr/.

تجاوز رموز اللغة والبلد باستخدام ملفات تعريف الارتباط

يمكنك تغيير المحتوى الذي يتم عرضه باستخدام ملفات تعريف الارتباط لتجاوز عناوين البلد واللغة.

في ما يلي بعض الطرق التي يمكنك من خلالها استخدام عمليات إلغاء ملفات تعريف الارتباط:

• اختبِر ميزة باستخدام مجموعات مختلفة من اللغات والبلدان لمعرفة المحتوى الذي يتم عرضه.

• يمكنك السماح للمستخدمين بتغيير المحتوى الذي يظهر لهم. على سبيل المثال، يمكنك تنفيذ أداة اختيار اللغة، ثم ضبط ملف تعريف الارتباط firebase-language-override الخاص بالمستخدم وفقًا لذلك.

لضبط عمليات إلغاء ملفات تعريف الارتباط، اضبط ملفات تعريف الارتباط باستخدام أحد الاسمين التاليين أو كليهما: firebase-country-override وfirebase-language-override. على سبيل المثال، يستبدل مقتطف رمز JavaScript التالي رمز البلد بـ ca ويستبدل العنوان Accept-Language بـ fr,en:

document.cookie = "firebase-country-override=ca";
document.cookie = "firebase-language-override=fr,en";

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

لا تظهر عمليات إلغاء ملفات تعريف الارتباط في السجلات.