設定國際化 (i18n) 重寫

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

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

• 向偏好法文的使用者放送標準法文內容，但向偏好法文的加拿大使用者放送加拿大法文內容。
  範例：首頁使用標準法文片語，與首頁使用加拿大法文片語

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

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

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

設定國際化重新編寫

如要為 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 目錄或其他子資料夾中也有類似檔案。您可以建立完全針對特定語言和/或國家/地區的內容。

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 內容」子資料夾名稱中的語言代碼不得包含這些子標記。舉例來說，您無法在子資料夾名稱中使用 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 content」的優先順序

如果您設定 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

  答案

  index.html fr_ca/ 子資料夾

  由於 Hosting 會先搜尋 fr_ca/ 子資料夾，因此會在該子資料夾中找到 index.html 的完全相符項目。

• 要求頁面：awesome-page.html

  答案

  404.html fr/ 子資料夾

  Hosting 會先依優先順序搜尋整個目錄 (包括所有「i18n 內容」子資料夾和根目錄)，尋找完全相符的項目，但找不到與 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/ 子資料夾是等效的。不過，如果兩個子資料夾都存在，Hosting 會先提供 fr_ALL/ 內容，再提供 fr/ 內容。

使用 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 覆寫。