Join us in person and online for Firebase Summit on October 18, 2022. Learn how Firebase can help you accelerate app development, release your app with confidence, and scale with ease. Register now

配置國際化 (i18n) 重寫

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

使用國際化重寫(“i18n 重寫”)根據用戶的國家或首選語言提供不同的內容。以下是您可以設置的一些示例配置:

  • 所有喜歡法語的用戶提供相同的法語內容(無論國家/地區)。
    示例:帶有法語文本的主頁

  • 向喜歡法語的用戶提供標準法語內容,但為喜歡法語的加拿大用戶提供加拿大法語內容。
    示例:帶有標準法語短語的主頁與帶有加拿大法語短語的主頁

  • 所有加拿大用戶提供相同的內容(無論他們的語言偏好如何)。
    示例:使用您網站的“默認”語言但具有加拿大特定功能(如假日主題)的主頁

  • 向喜歡法語的加拿大用戶提供加拿大法語內容。
    示例:帶有加拿大法語措辭和加拿大特定功能(如假日主題)的主頁

Firebase 託管根據用戶的 IP 地址確定用戶所在的國家/地區,並根據Accept-Language請求標頭(通常由他們的網絡瀏覽器自動設置)確定用戶的語言首選項。

設置 i18n 重寫

要為您的託管站點設置 i18n 重寫,您需要為所有本地化內容創建一個“i18n 內容”目錄,然後將i18n屬性添加到您的firebase.json文件以指向您的新“i18n 內容”目錄。

以下是詳細步驟:

  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
    

    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 內容”和配置部署到您的託管站點。

您可以使用cookie overrides測試您的設置。

國家和語言代碼

命名“i18n 內容”子文件夾時,國家和語言代碼必須使用小寫。您可以使用ALL的值(區分大小寫)來指示任何國家(如es_ALL/ )或任何語言(如ALL_ca/ )。

Hosting 從用戶的 IP 地址獲取國家代碼。國家代碼是兩個字母的ISO 3166-1 alpha-2 代碼

語言代碼是從用戶的Accept-Language請求標頭中獲取的(通常由他們的 Web 瀏覽器自動設置)。它們是ISO 639-1 代碼。使用語言代碼時請記住以下幾點:

  • 當 Hosting 搜索要服務的“i18n 內容”時,它會根據Accept-Language標頭中的質量值對語言進行排序。

  • Hosting 會在Accept-Language標頭中刪除任何區域和國家/地區子標籤,因此“i18n 內容”子文件夾名稱中的語言代碼不能包含這些子標籤。例如,您不能使用es-419es-US作為子文件夾名稱中的語言代碼,但可以使用es

    如果您想提供特定區域或國家/地區的內容,您可以創建包含您要支持的特定語言國家/地區內容的子文件夾。

“i18n 內容”的優先順序

如果您設置 i18n 重寫,Hosting 會根據以下優先級順序提供內容:

  1. /__/*路徑段開頭的保留命名空間

  2. 配置的重定向

  3. 完全匹配的靜態內容

    1. 語言代碼 + 國家代碼(例如,來自fr_ca/的內容)
      該順序遵循請求的Accept-Language標頭中每種語言的質量值。

    2. 僅國家代碼(例如,來自ALL_ca/的內容)

    3. 僅語言代碼(例如,來自fr/es_ALL/的內容)
      該順序遵循請求的Accept-Language標頭中每種語言的質量值。

    4. “默認”完全匹配的靜態內容
      這是“i18n 內容”目錄之外的內容,例如public目錄的根目錄。

  4. 配置的重寫

  5. 404處理

    1. i18n 404 頁
      這遵循上面列出的完全匹配靜態內容的相同優先級順序。

    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
    
  • 示例請求信息

    • 語言代碼: fren (法語,然後是英語)
      語言代碼根據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/子文件夾,上面的示例請求也不包含eses-foo語言代碼,因此 Hosting 不會搜索與es匹配的“i18n 內容”。

  • 從用戶的國家和語言偏好的角度來看,名為fr/fr_ALL/的子文件夾是等效的。但是,如果兩個子文件夾都存在,Hosting 將在fr/內容之前提供fr_ALL/內容。

您可以通過使用 cookie 覆蓋國家和語言標題來更改提供的內容。

以下是您可以使用 cookie 覆蓋的一些方法:

  • 測試具有不同語言/國家組合的功能,以檢查提供哪些內容。

  • 使您的用戶能夠更改他們看到的內容。例如,您可以實現一個語言選擇器,然後相應地設置用戶的firebase-language-override cookie。

要配置 cookie 覆蓋,請使用以下兩個名稱或其中一個名稱設置 cookie: firebase-country-overridefirebase-language-override 。例如,以下 JavaScript 代碼片段將國家代碼覆蓋為ca並將Accept-Language標頭覆蓋為fr,en

document.cookie = "firebase-country-override=ca";
document.cookie = "firebase-language-override=fr,en";

語言 cookie 覆蓋必須是按優先順序排列的以逗號分隔的語言代碼列表,沒有子標籤或質量值。

Cookie 覆蓋不會反映在日誌中。