配置国际化 (i18n) 重写

使用国际化重写(“i18n 重写”)根据用户的国家或首选语言提供不同的内容。以下是您可以设置的一些示例配置:

  • 所有喜欢法语的用户提供相同的法语内容(无论国家/地区)。
    示例:带有法语文本的主页

  • 向喜欢法语的用户提供标准法语内容,但为喜欢法语的加拿大用户提供加拿大法语内容。
    示例:带有标准法语短语的主页与带有加拿大法语短语的主页

  • 所有加拿大用户提供相同的内容(无论他们的语言偏好如何)。
    示例:使用您网站的“默认”语言但具有加拿大特定功能(如假日主题)的主页

  • 向喜欢法语的加拿大用户提供加拿大法语内容。
    示例:带有加拿大法语措辞和加拿大特定功能(如假日主题)的主页

Firebase 托管根据用户的 IP 地址确定用户所在的国家/地区,并根据Accept-Language请求标头(通常由他们的网络浏览器自动设置)确定用户的语言首选项。

设置 i18n 重写

要为您的托管站点设置 i18n 重写,您需要为所有本地化内容创建一个“i18n 内容”目录,然后将i18n属性添加到您的firebase.json文件以指向您的新“i18n 内容”目录。

以下是详细步骤:

  1. 在您本地应用程序目录的public中,为您的“i18n 内容”创建一个单独的目录,然后为您的站点支持的每种语言和国家/地区组合创建子文件夹。

    在每个子文件夹中,添加特定于该组合的内容,例如以假日为主题的主页或特定语言的 404 页面。

    这是一个名为localized-files的示例“i18n 内容”目录:

    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
    

    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 内容”子文件夹的目录的名称。如果您将所有“i18n 内容”子文件夹放在public目录的根目录下,请使用/作为root的值。 root值中的前导和尾随斜杠是可选的。

  3. 将您的“i18n 内容”和配置部署到您的托管站点。

您可以使用cookie overrides测试您的设置。

国家和语言代码

命名“i18n 内容”子文件夹时,国家和语言代码必须使用小写。您可以使用ALL的值(区分大小写)来指示任何国家(如es_ALL/ )或任何语言(如ALL_ca/ )。

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

语言代码是从用户的Accept-Language请求标头中获取的(通常由他们的 Web 浏览器自动设置)。它们是ISO 639-1 代码。使用语言代码时请记住以下几点:

  • 当 Hosting 搜索要服务的“i18n 内容”时,它会根据Accept-Language标头中的质量值对语言进行排序。

  • Hosting 会在Accept-Language标头中删除任何区域和国家/地区子标签,因此“i18n 内容”子文件夹名称中的语言代码不能包含这些子标签。例如,您不能使用es-419es-US作为子文件夹名称中的语言代码,但可以使用es

    如果您想提供特定区域或国家/地区的内容,您可以创建包含您要支持的特定语言国家/地区内容的子文件夹。

“i18n 内容”的优先顺序

如果您设置 i18n 重写,Hosting 会根据以下优先级顺序提供内容:

  1. /__/*路径段开头的保留命名空间

  2. 配置的重定向

  3. 完全匹配的静态内容

    1. 语言代码 + 国家代码(例如,来自fr_ca/的内容)
      该顺序遵循请求的Accept-Language标头中每种语言的质量值。

    2. 仅国家代码(例如,来自ALL_ca/的内容)

    3. 仅语言代码(例如,来自fr/es_ALL/的内容)
      该顺序遵循请求的Accept-Language标头中每种语言的质量值。

    4. “默认”完全匹配的静态内容
      这是“i18n 内容”目录之外的内容,例如public目录的根目录。

  4. 配置的重写

  5. 404处理

    1. i18n 404 页
      这遵循上面列出的完全匹配静态内容的相同优先级顺序。

    2. 自定义 404页面

    3. 默认 404 页面(由 Firebase 提供)

优先顺序示例

让我们从上面继续我们的例子。我们将使用相同的示例目录和示例请求。

  • 具有“i18n 内容”目录的示例本地项目目录(称为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
    
  • 示例请求信息

    • 语言代码: fren (法语,然后是英语)
      语言代码根据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

  • 请求页面: awesome-page.html

请注意以下关于“i18n 内容”目录的搜索和服务:

  • localized-files/目录实际上不包含en_ca/en_ALL/en/子文件夹,因此 Hosting 只会跳过优先级列表,直到找到与请求的语言-国家组合匹配的子文件夹。

  • 即使localized-files/目录包含es_ALL/子文件夹,上面的示例请求也不包含eses-foo语言代码,因此 Hosting 不会搜索与es匹配的“i18n 内容”。

  • 从用户的国家和语言偏好的角度来看,名为fr/fr_ALL/的子文件夹是等效的。但是,如果两个子文件夹都存在,Hosting 将在fr/内容之前提供fr_ALL/内容。

您可以通过使用 cookie 覆盖国家和语言标题来更改提供的内容。

以下是您可以使用 cookie 覆盖的一些方法:

  • 测试具有不同语言/国家组合的功能,以检查提供哪些内容。

  • 使您的用户能够更改他们看到的内容。例如,您可以实现一个语言选择器,然后相应地设置用户的firebase-language-override cookie。

要配置 cookie 覆盖,请使用以下两个名称或其中一个名称设置 cookie: firebase-country-overridefirebase-language-override 。例如,以下 JavaScript 代码片段将国家代码覆盖为ca并将Accept-Language标头覆盖为fr,en

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

语言 cookie 覆盖必须是按优先顺序排列的以逗号分隔的语言代码列表,没有子标签或质量值。

Cookie 覆盖不会反映在日志中。