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

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

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

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

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

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

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

הגדרת כתיבה מחדש של כתובות URL ל-i18n

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

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

1. בתיקייה public של ספריית האפליקציות המקומיות, יוצרים תיקייה נפרדת ל'תוכן i18n', ואז יוצרים תיקיות משנה לכל שילוב של שפה ומדינה שהאתר תומך בהם.

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

   לדוגמה, ספרייה בשם localized-files שכוללת תוכן i18n:

   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'

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