Configurar substituições de internacionalização (i18n)

Use substituições de internacionalização ("substituições de i18n") para exibir um conteúdo diferente dependendo do país ou do idioma preferido do usuário. Veja alguns exemplos de configurações que você pode definir:

  • Exibir o mesmo conteúdo em francês para todos os usuários que preferem o francês (independentemente do país).
    Exemplo: uma página inicial com texto em francês

  • Exibir o conteúdo em francês padrão para usuários que preferem o francês, mas, para usuários do Canadá que preferem francês, exibir conteúdo em francês canadense.
    Exemplo: uma página inicial em francês padrão em vez de uma página inicial em francês canadense

  • Exibir o mesmo conteúdo para todos os usuários canadenses (independentemente da preferência de idioma).
    Exemplo: uma página inicial com o idioma "padrão" do seu site, mas com um recurso específico do Canadá (como um tema de fim de ano)

  • Exibir conteúdo em francês canadense para usuários canadenses que preferem francês.
    Exemplo: uma página inicial em francês canadense e um recurso específico do Canadá (como um tema de fim de ano)

O Firebase Hosting determina o país de um usuário a partir do endereço IP e as preferências de idioma do usuário a partir do cabeçalho de solicitação Accept-Language (geralmente definido automaticamente pelo navegador da Web).

Configurar substituições de i18n

Para configurar as substituições de i18n para seu site do Hosting, você precisa criar um diretório "conteúdo de i18n" para todo o conteúdo localizado e, em seguida, adicionar o atributo i18n ao arquivo firebase.json para apontar para o novo diretório "conteúdo de i18n".

Veja as etapas detalhadas:

  1. Na pasta public do diretório de aplicativos local, crie um diretório separado para o "conteúdo de i18n" e crie subpastas para cada combinação de idioma e país aceita pelo seu site.

    Em cada subpasta, adicione o conteúdo específico para essa combinação, como páginas iniciais com tema de fim de ano ou páginas 404 específicas de cada idioma.

    Veja um exemplo de diretório "conteúdo de i18n" chamado 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
    

    O diretório localized-files/ contém subpastas separadas para cada combinação de idioma e país aceita pelo seu site. O padrão de nomenclatura para cada subpasta precisa seguir um destes formatos:

    • languageCode_countryCode: apresenta o conteúdo específico para usuários que têm a preferência de idioma e o código do país.

    • languageCode: conteúdo específico para usuários que têm preferência de idioma, mas o conteúdo não é específico do país. Basicamente equivalente a languageCode_ALL

    Consulte a subseção Códigos de país e idioma abaixo para mais detalhes sobre esses códigos. É possível usar o valor de ALL (diferencia maiúsculas de minúsculas) para indicar qualquer país (como es_ALL/) ou qualquer idioma (como ALL_ca/).

    Os arquivos em uma subpasta não precisam ter arquivos análogos no diretório public ou em outras subpastas. Você pode criar conteúdo totalmente específico para um idioma e/ou país.

  2. Adicione o atributo i18n ao seu arquivo firebase.json e especifique o diretório que contém seu "conteúdo de i18n". Continuando nosso exemplo:

    // firebase.json
    
    "hosting": {
    
      "public": "public",
    
      "ignore": [
        "firebase.json",
        "**/.*",
        "**/node_modules/**"
      ],
    
      "i18n": {
        "root": "/localized-files"  // directory that contains your "i18n content"
      }
    
      ...
    }
    

    O diretório especificado para root precisa ser o nome do diretório que contém todas as subpastas "conteúdo de i18n". Se você tiver colocado todas as subpastas "conteúdo de i18n" na raiz do diretório public, use / como o valor de root. As barras à esquerda e à direita no valor root são opcionais.

  3. Implante seu "conteúdo de i18n" e configure-o no site do Hosting.

É possível testar sua configuração usando substituições de cookies.

Códigos de país e idioma

Ao nomear as subpastas "conteúdo de i18n", use letras minúsculas para códigos de país e de idioma. É possível usar o valor de ALL (diferencia maiúsculas de minúsculas) para indicar qualquer país (como es_ALL/) ou qualquer idioma (como ALL_ca/).

O Hosting extrai o código do país do endereço IP do usuário. Os códigos de país são códigos ISO 3166-1 alfa-2 de duas letras.

Os códigos de idioma são extraídos do cabeçalho de solicitação Accept-Language do usuário (geralmente definido automaticamente pelo navegador da Web). Eles são códigos ISO 639-1. Informações importantes ao usar códigos de idioma:

  • Quando o Hosting pesquisa qual "conteúdo de i18n" será veiculado, ele ordena os idiomas com base nos valores de qualidade no cabeçalho Accept-Language.

  • O Hosting descarta todas as subtags regionais e de país no cabeçalho Accept-Language. Portanto, o código de idioma em um nome de subpasta "conteúdo de i18n" não pode conter essas subtags. Por exemplo, não é possível usar es-419 ou es-US como código de idioma em um nome de subpasta, mas você pode usar es.

    Se você quiser exibir conteúdo específico para a região ou o país, crie subpastas que contenham o conteúdo específico do idioma e país.

Ordem de prioridade para "conteúdo de i18n"

Se você configurar substituições de i18n, o Hosting exibirá conteúdo com base na seguinte ordem de prioridade:

  1. Namespaces reservados que começam com um segmento de caminho /__/*

  2. Redirecionamentos configurados

  3. Conteúdo estático de correspondência exata

    1. Código de idioma + código de país (por exemplo, conteúdo de fr_ca/)
      A ordem segue os valores de qualidade para cada idioma no cabeçalho Accept-Language da solicitação.

    2. Somente código de país (por exemplo, conteúdo de ALL_ca/)

    3. Somente código de idioma (por exemplo, conteúdo de fr/ ou es_ALL/)
      A ordem segue os valores de qualidade para cada idioma no cabeçalho Accept-Language da solicitação.

    4. Conteúdo estático de correspondência exata "padrão"
      É um conteúdo fora do diretório "conteúdo de i18n", como na raiz do diretório public.

  4. Substituições configuradas

  5. Processamento de 404

    1. Páginas de i18n 404
      Elas seguem a mesma ordem de prioridade listada acima para conteúdo estático de correspondência exata.

    2. Página 404 personalizada

    3. Página 404 padrão (fornecida pelo Firebase)

Exemplo de ordem de prioridade

Vamos continuar nosso exemplo acima. Usaremos o mesmo diretório de exemplo e uma solicitação de exemplo.

  • Exemplo de diretório de projeto local com um diretório "conteúdo de i18n" (chamado 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
    
  • Exemplo de informações da solicitação

    • Códigos de idioma: fr, en (francês e inglês)
      Os códigos de idioma são ordenados com base nos valores de qualidade no cabeçalho Accept-Language.

    • Código de país: ca (Canadá)

De acordo com a ordem de prioridade de correspondência exata e os valores de qualidade das preferências de idioma, o Hosting pesquisará nos diretórios uma página solicitada na seguinte ordem.

  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. Processamento de 404

Qual página vai aparecer para o usuário?

  • Página solicitada: index.html

  • Página solicitada: awesome-page.html

Observe o seguinte sobre a pesquisa e exibição do diretório "conteúdo de i18n":

  • O diretório localized-files/ não contém subpastas en_ca/, en_ALL/ ou en/. Portanto, o Hosting ignorará a lista de prioridades até encontrar uma subpasta correspondente para a combinação idioma/país da solicitação.

  • Mesmo que o diretório localized-files/ contenha uma subpasta es_ALL/, o exemplo de solicitação acima não inclui um código de idioma es ou es-foo, então, o Hosting não pesquisará por "conteúdo de i18n" que corresponda a es.

  • As subpastas chamadas fr/ e fr_ALL/ são equivalentes da perspectiva do país e do idioma de um usuário. Mas se as duas subpastas existirem, o Hosting vai exibir o conteúdo de fr_ALL/ antes do conteúdo de fr/.

É possível alterar qual conteúdo é exibido usando cookies para modificar os cabeçalhos de país e de idioma.

Veja algumas maneiras de usar substituições de cookies:

  • Testar um recurso com diferentes combinações de idioma/país para verificar qual conteúdo é exibido.

  • Permitir que os usuários alterem o conteúdo que veem. Por exemplo, é possível implementar um seletor de idioma e definir o cookie firebase-language-override do usuário de acordo.

Para configurar substituições de cookies, defina cookies com um ou ambos os nomes: firebase-country-override e firebase-language-override. Por exemplo, o snippet de código JavaScript a seguir modifica o código do país para ca e o cabeçalho Accept-Language para fr,en:

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

As substituições de cookies de idioma precisam ser uma lista separada por vírgulas de códigos de idioma em ordem de preferência, sem subtags ou valores de qualidade.

As substituições de cookies não são refletidas nos registros.