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

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

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

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

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

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

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

הגדרת כתיבה מחדש של כתובות URL לצורך התאמה לשוק הבינלאומי

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

אפשר לבדוק את ההגדרה באמצעות שינוי הגדרות ברירת המחדל של קובצי ה-Cookie.

קודים של מדינות ושפות

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

אם הגדרתם כתיבה מחדש של i18n, ‏ Hosting מציג תוכן לפי סדר העדיפויות הבא:

1. מרחבי שמות שמורים שמתחילים בפלח נתיב /__/*

2. הפניות שהוגדרו

3. תוכן סטטי עם התאמה מדויקת

   1. קוד שפה + קוד מדינה (לדוגמה, תוכן מ-fr_ca/)
      הסדר נקבע לפי ערכי האיכות של כל שפה בכותרת Accept-Language של הבקשה.

   2. רק קוד מדינה (לדוגמה, תוכן מ-ALL_ca/)

   3. קוד שפה בלבד (לדוגמה, תוכן מ-fr/ או מ-es_ALL/)
      הסדר נקבע לפי ערכי האיכות של כל שפה בכותרת Accept-Language של הבקשה.

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

שינוי קודי השפה והמדינה באמצעות קובצי 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 לא משתקפים ביומנים.