הגדרת שכתוב של אינטרנציונליזציה (i18n)

שימוש בכתיבה מחדש של תוכן לפי תרבות ('כתיבה מחדש לפי תרבות') כדי להציג תוכן שונה בהתאם למדינה או לשפה המועדפת של המשתמש. ריכזנו כאן כמה דוגמאות להגדרות שאפשר להגדיר:

• הצגת אותו תוכן בצרפתית לכל המשתמשים שמעדיפים את הצרפתית (ללא קשר למדינה).
  דוגמה: דף בית עם טקסט בצרפתית

• הצגת תוכן בצרפתית רגילה למשתמשים שמעדיפים צרפתית, אבל למשתמשים בקנדה שמעדיפים צרפתית, הצגת תוכן בצרפתית קנדית במקום זאת.
  דוגמה: דף בית עם ניסוח בצרפתית רגילה לעומת דף בית עם ניסוח בצרפתית קנדית

• הצגת אותו תוכן לכל המשתמשים בקנדה (ללא קשר להעדפת השפה שלהם).
  דוגמה: דף בית בשפת ברירת המחדל של האתר, אבל עם תכונה ספציפית לקנדה (למשל, נושא של חג)

• הצגת תוכן בצרפתית קנדית למשתמשים בקנדה שמעדיפים את הצרפתית.
  דוגמה: דף בית עם ניסוח בצרפתית קנדית ותכונה ספציפית לקנדה (למשל, נושא של חג)

Firebase Hosting קובע את המדינה של המשתמש לפי כתובת ה-IP שלו ואת העדפות השפה של המשתמש לפי כותרת הבקשה Accept-Language (בדרך כלל מוגדרות באופן אוטומטי על ידי דפדפן האינטרנט שלו).

הגדרת שכתוב של תוכן בשפות שונות

כדי להגדיר שכתובות של i18n ייכתבו מחדש באתר Hosting, צריך ליצור ספרייה בשם 'i18n content' לכל התוכן המתורגם, ואז להוסיף את המאפיין i18n לקובץ firebase.json כדי להפנות לספרייה החדשה 'i18n content'.

אלה השלבים המפורטים:

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 ומציינים את התיקייה שמכילה את 'תוכן התרגום'. בהמשך לדוגמה שלנו:

   // 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.

אתם יכולים לבדוק את ההגדרות באמצעות שינוי הגדרות ברירת המחדל של קובצי cookie.

קודי מדינה ושפה

כשנותנים שמות לתיקיות המשנה של 'תוכן ל-i18n', צריך להשתמש באותיות קטנות גם בקודי המדינות וגם בקודי השפות. אפשר להשתמש בערך ALL (לפי תווית רישיות) כדי לציין כל מדינה (כמו es_ALL/) או כל שפה (כמו ALL_ca/).

Hosting מקבל את קוד המדינה מכתובת ה-IP של המשתמש. קודי המדינות הם קודים לפי תקן ISO 3166-1 alpha-2 בני שתי אותיות.

קודי השפות מתקבלים מכותרת הבקשה Accept-Language של המשתמש (בדרך כלל מוגדרים באופן אוטומטי על ידי דפדפן האינטרנט שלו). אלה קודים לפי תקן ISO 639-1. כשמשתמשים בקודי שפות, חשוב לזכור את הדברים הבאים:

• כשה-Hosting מחפש איזה 'תוכן מותאם לשוק הבינלאומי' להציג, הוא ממיין את השפות על סמך ערכי האיכות בכותרת 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 content', למשל ברמה הבסיסית (root) של הספרייה public.

4. כתובות URL שעברו כתיבה מחדש שהוגדרו

5. טיפול בשגיאות 404

   1. דפי 404 ב-i18n
      התהליך הזה מתבצע לפי אותו סדר העדיפויות שמפורט למעלה לגבי תוכן סטטי תואם.

   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 מחפשת קודם את כל הספרייה (כולל כל התיקיות המשניות של 'תוכן i18n' ואת ספריית הבסיס) לפי סדר עדיפות כדי למצוא התאמה מדויקת, אבל אין התאמה מדויקת ל-awesome-page.html.

  לכן, Hosting תתחיל לטפל בשגיאה 404, לפי אותו סדר תעדוף של תרגום לשפות שונות כמו בחיפושים בהתאמה מדויקת. תיקיית המשנה fr/ היא תיקיית המשנה הראשונה שנבדקת ומכילה דף 404.

חשוב לשים לב לנקודות הבאות לגבי החיפוש וההצגה של ספריית 'תוכן i18n':

• הספרייה 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/.

שינוי קודי השפה והמדינה באמצעות קובצי cookie

אתם יכולים לשנות את התוכן שמוצג באמצעות קובצי cookie כדי לשנות את הכותרות של המדינה והשפה.

ריכזנו כאן כמה דרכים שבהן אפשר להשתמש בשינויים מברירת המחדל של קובצי cookie:

• כדאי לבדוק תכונה עם שילובים שונים של שפות או מדינות כדי לבדוק איזה תוכן מוצג.

• מאפשרים למשתמשים לשנות את התוכן שהם רואים. לדוגמה, אפשר להטמיע בורר שפות ולאחר מכן להגדיר את קובץ ה-cookie firebase-language-override של המשתמש בהתאם.

כדי להגדיר שינויים שמוגדרים מראש בקובצי cookie, צריך להגדיר קובצי cookie עם שני השמות האלה או עם אחד מהם: 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";

שינויים שמוגדרים ב-cookie של השפה חייבים להיות רשימה של קודי שפות מופרדים בפסיקים לפי סדר העדפה, ללא תגי משנה או ערכי איכות.

שינויים קובעים של קובצי cookie לא משתקפים ביומני המערכת.