ضبط إعادة كتابة الترجمات التدويلية (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 content" (يُعرف باسم 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";

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

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