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

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 بتنسيق i18n
      يتبع هذا الترتيب نفسه المُدرَج أعلاه للمحتوى الثابت الذي يتطابق تمامًا مع المحتوى الأصلي.

   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، والذي يتّبع ترتيب الأولوية نفسه لترجمة محتوى الموقع الإلكتروني الذي تتّبعه عمليات البحث التي تستخدم المطابقة التامة. الدليل الفرعي 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";

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

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