配置国际化 (i18n) 重写

使用国际化重写（“i18n 重写”）可根据用户所在的国家/地区或偏好语言提供不同的内容。下面是您可以设置的一些配置示例：

• 向所有习惯使用法语的用户（无论其位于哪个国家/地区）提供相同的法语内容。
  示例：采用法语文字的首页

• 向习惯使用法语的用户提供标准法语内容，但对于习惯使用法语的加拿大用户，改为提供加拿大法语内容。
  示例：采用标准法语表述方式的首页与采用加拿大法语表述方式的首页

• 向所有加拿大用户（无论其语言偏好如何）提供相同的内容。
  示例：采用您网站的“默认”语言但具有特定于加拿大的功能（例如节假日主题）的网页

• 向习惯使用法语的加拿大用户提供加拿大法语内容。
  示例：采用加拿大法语表述方式并具有特定于加拿大的功能（如节假日主题）的首页

Firebase Hosting 会根据用户的 IP 地址确定其所在的国家/地区，并根据 Accept-Language 请求标头（通常由网络浏览器自动设置）确定其语言偏好。

设置 i18n 重写

如需为您的 Hosting 网站设置 i18n 重写，您需要为所有本地化内容创建“i18n content”目录，然后将 i18n 属性添加到 firebase.json 文件以指向新的“i18n content”目录。

下面是详细步骤：

1. 在本地应用目录的 public 文件夹中，为您的“i18n content”创建单独的目录，然后为您的网站支持的每种语言和国家/地区组合创建子文件夹。

   在每个子文件夹中，添加特定于该组合的内容，例如节假日主题的首页或特定语言的 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 content”的优先级顺序，了解 Hosting 提供您的“i18n content”文件的顺序。

2. 将 i18n 特性添加到 firebase.json 文件中，并指定包含“i18n content”的目录。继续我们的示例：

   // 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 content”和配置部署到您的 Hosting 网站。

您可以使用 Cookie 替换值来测试设置。

国家/地区代码和语言代码

为“i18n content”子文件夹命名时，国家/地区代码和语言代码必须采用小写字母。您可以使用 ALL 的值（区分大小写）来表示任何国家/地区（如 es_ALL/）或任何语言（如 ALL_ca/）。

Hosting 会从用户的 IP 地址获取国家/地区代码。国家/地区代码是由两个字母组成的 ISO 3166-1 alpha-2 代码。

语言代码是从用户的 Accept-Language 请求标头（通常由网络浏览器自动设置）获取的。 这些代码是 ISO 639-1 代码。 使用语言代码时，请注意以下几点：

• 当 Hosting 搜索要提供的“i18n content”时，会根据 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 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

  答案

  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 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 替换值不会反映在日志中。