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