Настроить перезапись интернационализации (i18n)

Используйте перезапись интернационализации («перезапись i18n») для предоставления различного контента в зависимости от страны пользователя или предпочтительного языка. Вот несколько примеров конфигураций, которые вы можете настроить:

  • Предоставляйте один и тот же контент на французском языке всем пользователям, предпочитающим французский язык (независимо от страны).
    Пример: домашняя страница с французским текстом

  • Предоставляйте контент на стандартном французском языке пользователям, предпочитающим французский язык, но пользователям из Канады , предпочитающим французский язык, вместо этого предоставляйте контент на канадском французском языке.
    Пример: домашняя страница со стандартной французской формулировкой по сравнению с домашней страницей с канадской французской формулировкой.

  • Предоставьте один и тот же контент всем канадским пользователям (независимо от их языковых предпочтений).
    Пример: домашняя страница с языком вашего сайта по умолчанию, но с особенностью, характерной для Канады (например, праздничной темой).

  • Предоставляйте канадско-французский контент пользователям из Канады, предпочитающим французский язык.
    Пример: домашняя страница с канадско-французской формулировкой и особенностью Канады (например, праздничной темой).

Firebase Hosting определяет страну пользователя по его IP-адресу и языковые предпочтения пользователя по заголовку запроса Accept-Language (обычно устанавливается автоматически их веб-браузером ).

Настройка перезаписей i18n

Чтобы настроить перезапись i18n для вашего хостинг-сайта, вам нужно создать каталог «i18n content» для всего вашего локализованного контента, а затем добавить атрибут i18n в ваш файл firebase.json , чтобы указать на ваш новый каталог «i18n content».

Вот подробные шаги:

  1. В public папке вашего локального каталога приложений создайте отдельный каталог для своего «контента i18n», а затем создайте подпапки для каждой комбинации языка и страны, поддерживаемой вашим сайтом.

    В каждую подпапку добавьте содержимое, характерное для этой комбинации, например, домашние страницы с праздничной тематикой или страницы 404 для конкретного языка.

    Вот пример каталога «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
    

    Каталог 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 пользователя (обычно устанавливаются автоматически их веб-браузером ). Это коды ISO 639-1 . При использовании языковых кодов помните следующее:

  • Когда хостинг ищет, какой «контент i18n» обслуживать, он упорядочивает языки на основе значений качества в заголовке Accept-Language .

  • Хостинг удаляет все вложенные теги региона и страны в заголовке Accept-Language , поэтому код языка в имени подпапки «i18n content» не может содержать эти вложенные теги. Например, вы не можете использовать es-419 или es-US в качестве кода языка в имени подпапки, но вы можете использовать es .

    Если вы хотите обслуживать определенный региональный или национальный контент, вы можете создать вложенные папки, содержащие контент для определенного языка и страны, который вы хотите поддерживать.

Приоритетный порядок для «контента i18n»

Если вы настроили перезапись 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. 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 (Канада)

В соответствии с порядком приоритета точного совпадения и значениями качества для языковых настроек Хостинг будет искать каталоги для запрошенной страницы в следующем порядке.

  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 content»:

  • Каталог localized-files/ на самом деле не содержит en_ca/ , en_ALL/ или en/ , поэтому служба хостинга просто пропустит список приоритетов, пока не найдет соответствующую подпапку для комбинации языка и страны запроса.

  • Несмотря на то, что каталог localized-files/ содержит es_ALL/ , приведенный выше пример запроса не включает код языка es или es-foo , поэтому Hosting не будет искать «контент i18n», соответствующий es .

  • Подпапки с именами fr/ и fr_ALL/ эквивалентны с точки зрения страны пользователя и языковых предпочтений. Однако, если существуют обе подпапки, Hosting будет обслуживать fr_ALL/ content перед fr/ content.

Вы можете изменить контент, который будет обслуживаться, используя файлы cookie для переопределения заголовков страны и языка.

Вот несколько способов переопределения файлов cookie:

  • Протестируйте функцию с различными комбинациями языка/страны, чтобы проверить, какой контент обслуживается.

  • Позвольте вашим пользователям изменять контент, который они видят. Например, вы можете реализовать средство выбора языка, а затем соответствующим образом установить пользовательский файл cookie firebase-language-override .

Чтобы настроить переопределение файлов 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 не отражаются в журналах.