配置國際化 (i18n) 重寫

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

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

  • 向喜歡法語的用戶提供標準法語內容,但對於喜歡法語的加拿大用戶,則提供加拿大法語內容。
    示例:使用標準法語措辭的主頁與使用加拿大法語措辭的主頁

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

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

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

設置 i18n 重寫

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

以下是詳細步驟:

  1. 在本地應用程序目錄的public文件夾中,為“i18n 內容”創建一個單獨的目錄,然後為站點支持的每種語言和國家/地區組合創建子文件夾。

    在每個子文件夾中,添加特定於該組合的內容,例如假日主題主頁或特定語言的 404 頁面。

    這是一個名為localized-files的“i18n content”目錄示例:

    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 content”子文件夾的目錄的名稱。如果您將所有“i18n content”子文件夾放置在public目錄的根目錄中,請使用/作為root的值。 root值中的前導斜杠和尾隨斜杠是可選的。

  3. 將您的“i18n 內容”和配置部署到您的託管站點。

您可以使用cookie 覆蓋來測試您的設置。

國家和語言代碼

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

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

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

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

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

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

“國際化內容”的優先順序

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

  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 頁
      這遵循上面列出的完全匹配靜態內容的相同優先級順序。

    2. 自定義 404頁面

    3. 默認 404 頁面(由 Firebase 提供)

優先順序示例

讓我們繼續上面的例子。我們將使用相同的示例目錄和示例請求。

  • 具有“i18n content”目錄的示例本地項目目錄(稱為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 content”目錄的搜索和服務的內容:

  • localized-files/目錄實際上並不包含en_ca/en_ALL/en/子文件夾,因此 Hosting 將跳過優先級列表,直到找到與請求的語言/國家/地區組合匹配的子文件夾。

  • 儘管localized-files/目錄包含es_ALL/子文件夾,但上面的示例請求不包含eses-foo語言代碼,因此 Hosting 不會搜索與es匹配的“i18n 內容”。

  • 從用戶的國家/地區和語言首選項的角度來看,名為fr/fr_ALL/的子文件夾是等效的。但是,如果兩個子文件夾都存在,託管將在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 覆蓋不會反映在日誌中。