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

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

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

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

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

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

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

إعداد عمليات إعادة الكتابة بلغات مختلفة

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

في ما يلي الخطوات المفصّلة:

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

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

   في ما يلي مثال على دليل "محتوى i18n" باسم 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 أو المجلدات الفرعية الأخرى. يمكنك إنشاء محتوى مخصّص بالكامل للغة و/أو البلد.

   ملاحظة: راجِع ترتيب الأولوية لـ "المحتوى المتوافق مع i18n" أدناه لمعرفة الترتيب الذي يعرض به Hosting ملفات "المحتوى المتوافق مع i18n".

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

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

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

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

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

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

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

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

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

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

• تُزيل Hosting أيّ علامات فرعية للمنطقة والبلد في عنوان Accept-Language ، لذا لا يمكن أن يحتوي رمز اللغة في اسم المجلد الفرعي "محتوى i18n" على هذه العلامات الفرعية. على سبيل المثال، لا يمكنك استخدام 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. صفحات 404 المترجَمة
      تتبع هذه الصفحات ترتيب الأولوية نفسه المُدرَج أعلاه للمحتوى الثابت الذي يتطابق تمامًا مع محتوى الصفحة الأصلية.

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

   3. صفحة 404 التلقائية (توفّرها Firebase)

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

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

• مثال على دليل مشروع على الجهاز يتضمّن دليل "محتوى i18n" (يُسمى 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 content" وعرض هذا المحتوى:

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

• على الرغم من أنّ دليل localized-files/ يحتوي على مجلد فرعي es_ALL/ ، لا يتضمّن مثال الطلب أعلاه رمز لغة es أو es-foo ، لذا لن يبحث Hosting عن "محتوى i18n" الذي يتطابق مع 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";

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

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