הגדרת שכתוב של אינטרנציונליזציה (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

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

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

סדר העדיפויות של 'תוכן ב-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

  • הדף המבוקש: awesome-page.html

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