配置國際化 (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
   

   查看每個子文件夾內容的匹配請求

   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 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-419或es-US作為子文件夾名稱中的語言代碼，但可以使用es 。

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

  查看支持特定區域或國家內容的示例

  提供適用於西班牙與任何其他國家/地區的西班牙語內容（模仿es-419的行為）

  在此示例中，來自西班牙且語言首選項為es 、 es-es甚至es-419的請求將從es_es/子文件夾接收內容，因為 Hosting 將所有這些語言代碼視為es 。

  來自美國、墨西哥或任何其他語言首選項為es-419的國家/地區的請求將收到es_ALL/子文件夾中的內容，因為託管將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/子文件夾接收內容，因為託管將語言代碼es-419視為es 。

  但是，來自美國且語言首選項為es-419的請求將收到來自es_ALL/子文件夾的內容，因為託管將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 重寫，託管將根據以下優先級順序提供內容：

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
  

• 請求信息示例

  • 語言代碼： 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

  回答

  fr_ca/子文件夾中的index.html

  由於 Hosting 首先搜索fr_ca/子文件夾，因此它將在該子文件夾中找到與index.html完全匹配的內容。

• 請求的頁面： awesome-page.html

  回答

  fr/子文件夾中的404.html

  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 不會搜索與es匹配的“i18n 內容”。

• 從用戶的國家/地區和語言首選項的角度來看，名為fr/和fr_ALL/的子文件夾是等效的。但是，如果兩個子文件夾都存在，託管將在fr/內容之前提供fr_ALL/內容。

使用 cookie 覆蓋語言和國家/地區代碼

您可以使用 cookie 覆蓋國家/地區和語言標頭來更改所提供的內容。

您可以通過以下方式使用 cookie 覆蓋：

• 使用不同的語言/國家/地區組合測試功能，以檢查提供哪些內容。

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

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