Check out what’s new from Firebase at Google I/O 2022. Learn more

配置國際化 (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 覆蓋不會反映在日誌中。