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

להשתמש בשכתובים לבינלאומיות ('שכתובים של 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 או בתיקיות משנה אחרות. אפשר ליצור תוכן שהוא ספציפי לחלוטין לשפה ו/או למדינה.

   הערה: בקטע הבא מוסבר סדר העדיפויות של 'תוכן ב-i18n', כדי שתוכלו להבין את הסדר שבו Hosting מציג את הקבצים של 'תוכן ב-i18n'.

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