設定國際化 (i18n) 重寫

使用國際化重寫 (「i18n 改寫」)，根據使用者的國家/地區或偏好語言提供不同內容。以下列舉幾個您可以設定的設定範例：

• 為所有偏好法文的使用者 (不論國家/地區為何) 提供相同的法文內容。
  範例：使用法文的首頁

• 如果使用者偏好法文，請向他們提供標準法文內容；如果使用者偏好法文 (加拿大)，請向他們提供法文 (加拿大) 內容。
  範例：使用標準法文的首頁與使用加拿大法文的首頁

• 為所有加拿大使用者提供相同的內容 (不論他們偏好的語言為何)。
  範例：首頁使用網站的「預設」語言，但提供加拿大專屬功能 (例如節日主題)

• 為偏好法文的加拿大使用者提供法文 (加拿大) 內容。
  示例：首頁使用加拿大法文用語，並提供加拿大專屬功能 (例如節慶主題)

Firebase Hosting 會根據使用者的 IP 位址判斷使用者所在國家/地區，並根據 Accept-Language 要求標頭判斷使用者的語言偏好設定 (通常是由使用者的網路瀏覽器自動設定)。

設定 i18n 重寫

如要為 Hosting 網站設定 i18n 重寫功能，您需要為所有本地化內容建立「i18n 內容」目錄，然後將 i18n 屬性新增至 firebase.json 檔案，以便指向新的「i18n 內容」目錄。

詳細步驟如下：

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 目錄或其他子資料夾中具有類似的檔案。您可以建立專屬於特定語言和/或國家/地區的內容。

   注意： 請詳閱下方的「i18n 內容」的優先順序，瞭解 Hosting 提供「i18n 內容」檔案的順序。

2. 在 firebase.json 檔案中加入 i18n 屬性，並指定包含「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 內容」和設定部署至 Hosting 網站。

您可以使用 Cookie 覆寫來測試設定。

國家/地區和語言代碼

為「i18n 內容」子資料夾命名時，請務必使用小寫的國家/地區和語言代碼。您可以使用 ALL 的值 (區分大小寫) 來表示任何國家/地區 (例如 es_ALL/) 或任何語言 (例如 ALL_ca/)。

Hosting 會從使用者的 IP 位址取得國家/地區代碼。國家/地區代碼是兩個英文字母的 ISO 3166-1 alpha-2 代碼。

系統會從使用者的 Accept-Language 要求標頭取得語言代碼 (通常會由網路瀏覽器自動設定)。格式為 ISO 639-1。使用語言代碼時，請注意下列事項：

• Hosting 搜尋要放送的「i18n 內容」時，會根據 Accept-Language 標頭中的品質值排序語言。

• Hosting 會捨棄 Accept-Language 標頭中的任何地區和國家/地區子標記，因此「i18n content」子資料夾名稱中的語言代碼不能包含這些子標記。舉例來說，您不能使用 es-419 或 es-US 做為子資料夾名稱中的語言代碼，但可以使用 es。

  如果您想提供特定的國家/地區或國家/地區內容，可以建立子資料夾，其中包含您要支援的特定語言國家/地區內容。

  查看相關例子，支持特定區域或國家/地區內容

  針對西班牙提供適用的西班牙文內容，而非任何其他國家/地區 (模仿 es-419 的行為)

  在這個範例中，來自西班牙的使用者如果偏好使用 es、es-es 或 es-419 語言，就會收到 es_es/ 子資料夾中的內容，因為 Hosting 會將所有這些語言代碼視為 es。

  來自美國、墨西哥或其他語言偏好為 es-419 的國家/地區的請求會收到 es_ALL/ 子資料夾的內容，因為 Hosting 會將 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/ 子資料夾的內容，因為 Hosting 會將語言代碼 es-419 視為 es。

  不過，來自美國且語言偏好設定為 es-419 的要求，會收到來自 es_ALL/ 子資料夾的內容，因為 Hosting 會將 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 內容」的優先順序

如果您設定 i18n 重寫，Hosting 會根據下列優先順序提供內容：

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. i18n 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 內容」子資料夾和根目錄) 以取得完全相符的項目，但 awesome-page.html 沒有完全相符的項目。

  因此，Hosting 會開始處理 404 錯誤，並遵循與完全比對搜尋相同的 i18n 優先順序。fr/ 子資料夾是搜尋時第一個包含 404 頁面的子資料夾。

請注意下列與「i18n content」目錄的搜尋及服務相關的事項：

• localized-files/ 目錄實際上不含 en_ca/、en_ALL/ 或 en/ 子目錄，因此 Hosting 會略過優先順序清單，直到找到與要求語言-國家/地區組合相符的子目錄為止。

• 雖然 localized-files/ 目錄包含 es_ALL/ 子資料夾，但上述範例 request 並未包含 es 或 es-foo 語言代碼，因此 Hosting 不會搜尋與 es 相符的「i18n content」。

• 從使用者的國家/地區和語言偏好設定來看，名為 fr/ 和 fr_ALL/ 的子資料夾是等同的。不過，如果兩個子資料夾都存在，Hosting 會先放送 fr_ALL/ 內容，再放送 fr/ 內容。

使用 Cookie 覆寫語言和國家/地區代碼

您可以使用 Cookie 覆寫國家/地區和語言標頭，藉此變更提供的內容。

以下是使用 Cookie 覆寫值的幾種方式：

• 使用不同的語言/國家/地區組合測試功能，確認系統會提供哪些內容。

• 讓使用者自行變更所見內容。舉例來說，您可以實作語言挑選器，然後據此設定使用者的 firebase-language-override Cookie。

如要設定 Cookie 覆寫值，請設定 firebase-country-override 和 firebase-language-override 這兩個名稱的 Cookie，舉例來說，下列 JavaScript 程式碼片段會將國家/地區代碼覆寫為 ca，並將 Accept-Language 標頭覆寫為 fr,en：

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

語言 Cookie 覆寫值必須是以逗號分隔的語言代碼清單，並依照偏好順序排列，不含子標記或品質值。

記錄檔中不會顯示 Cookie 覆寫值。