Configura reescrituras de internacionalización (i18n)

Usa reescrituras de internacionalización (“reescrituras de i18n”) para entregar contenido diferente según el país o el idioma de preferencia del usuario. Los siguientes son algunos ejemplos de configuración que puedes establecer:

  • Entrega el mismo contenido en francés para todos los usuarios que prefieren el francés (sin importar el país).
    Ejemplo: una página principal con texto en francés

  • Entrega contenido estándar en francés a los usuarios que prefieren este idioma y entrega contenido en francés de Canadá a los usuarios canadienses que prefieren el francés.
    Ejemplo: una página principal con una frase en francés estándar versus en francés canadiense

  • Entrega el mismo contenido a todos los usuarios canadienses (sin importar la preferencia de idioma).
    Ejemplo: una página principal con el idioma “predeterminado” de tu sitio, pero con una función específica para Canadá (como un tema festivo)

  • Entrega contenido en francés de Canadá a los usuarios canadienses que prefieren el francés.
    Ejemplo: una página principal con frases en francés canadiense y una función específica para Canadá (como un tema festivo)

Firebase Hosting determina el país de un usuario a partir de su dirección IP, y sus preferencias de idioma a partir del encabezado de la solicitud Accept-Language (por lo general, se establece automáticamente mediante su navegador web).

Configura reescrituras de i18n

Si quieres configurar reescrituras de i18n para tu sitio de Hosting, debes crear un directorio de “contenido de i18n” para todo el contenido localizado y, luego, agregar el atributo i18n a tu archivo firebase.json a fin de que apunte al nuevo directorio de “contenido de i18n”.

Estos son los pasos detallados:

  1. En la carpeta public del directorio de tu app local, crea un directorio separado para el “contenido de i18n” y, luego, crea subcarpetas para cada combinación de idioma y país compatible con tu sitio.

    En cada subcarpeta agrega el contenido específico para esa combinación, como páginas principales con temática festiva o páginas 404 específicas para un idioma.

    A continuación, se muestra un ejemplo de directorio de “contenido de i18n” llamado 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

    El directorio localized-files/ posee subcarpetas separadas para cada combinación de idioma y país compatible con tu sitio. El patrón para nombrar cada subcarpeta debe tener alguno de los siguientes formatos:

    • languageCode_countryCode: Incluye contenido específico para los usuarios que tienen esa preferencia de idioma y ese código de país

    • languageCode: Incluye contenido específico para los usuarios que tienen esa preferencia de idioma; sin embargo, el contenido no es específico para un país. Básicamente, equivale a languageCode_ALL

    Consulta la subsección Códigos de idioma y país que aparece a continuación para obtener más detalles sobre estos códigos. Puedes usar el valor de ALL (distingue entre mayúsculas y minúsculas) para indicar cualquier país (como es_ALL/) o cualquier idioma (como ALL_ca/).

    Los archivos en una subcarpeta no necesitan tener archivos análogos en el directorio public ni en otras subcarpetas. Puedes crear contenido que sea completamente específico para un idioma o país.

  2. Agrega el atributo i18n al archivo firebase.json y especifica el directorio que incluye el “contenido de i18n”. Continuación del ejemplo:

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

    El directorio especificado para root debe ser el nombre del directorio que contiene todas tus subcarpetas de “contenido de i18n”. Si colocaste todas las subcarpetas de “contenido de i18n” en la raíz del directorio public, usa / para el valor de root. Las barras iniciales y finales en el valor root son opcionales.

  3. Implementa el “contenido de i18n” y configúralo en tu sitio de Hosting.

Puedes probar la configuración mediante anulaciones de cookies.

Códigos de idioma y país

Cuando asignes nombres a subcarpetas de “contenido de i18n”, debes usar minúsculas para los códigos de idioma y país. Puedes usar el valor de ALL (distingue mayúsculas de minúsculas) para indicar cualquier país (como es_ALL/) o cualquier idioma (como ALL_ca/).

Hosting obtiene el código de país a partir de la dirección IP del usuario. Los códigos de país son códigos ISO 3166-1 alpha-2 de dos letras.

Los códigos de idioma se obtienen a partir del encabezado de la solicitud Accept-Language del usuario (por lo general, se establece automáticamente mediante su navegador web). Corresponden a códigos ISO 639-1. Ten en cuenta lo siguiente cuando uses códigos de idioma:

  • Cuando Hosting busca “contenido de i18n” para entregar, ordena los idiomas en función de los valores de calidad del encabezado Accept-Language.

  • Hosting descarta todas las subetiquetas regionales y de país del encabezado Accept-Language, por lo que el código de idioma en un nombre de subcarpeta de “contenido de i18n” no puede contener estas subetiquetas. Por ejemplo, no puedes usar es-419 ni es-US como código de idioma en un nombre de subcarpeta, pero sí puedes usar es.

    Si quieres entregar contenido específico regional o de país, puedes crear subcarpetas que incluyan el contenido de idioma y país específico que quieres admitir.

Orden de prioridad del “contenido de i18n”

Si configuras las reescrituras de i18n, Hosting entrega contenido según el siguiente orden de prioridad:

  1. Espacios de nombres reservados que comienzan con un segmento de ruta de acceso /__/*

  2. Redireccionamientos configurados

  3. Contenido estático de concordancia exacta

    1. Código de idioma + código de país (por ejemplo, contenido de fr_ca/)
      El orden sigue los valores de calidad de cada idioma en el encabezado Accept-Language de la solicitud.

    2. Solo código de país (por ejemplo, contenido de ALL_ca/)

    3. Solo código de idioma (por ejemplo, contenido de fr/ o es_ALL/)
      El orden sigue los valores de calidad de cada idioma en el encabezado Accept-Language de la solicitud.

    4. Contenido estático de concordancia exacta “predeterminado”
      Contenido que se encuentra fuera del directorio de “contenido de i18n”, como en la raíz del directorio public.

  4. Reescrituras configuradas

  5. Administración de páginas 404

    1. Página 404 de i18n
      Sigue el mismo orden de prioridad indicado anteriormente para el contenido estático de concordancia exacta.

    2. Página 404 personalizada

    3. Se refiere a la página 404 predeterminada (proporcionada por Firebase).

Ejemplo del orden de prioridad

Como continuación del ejemplo anterior, usaremos el mismo directorio de ejemplo y una solicitud de ejemplo.

  • Ejemplo de directorio de proyecto local con un directorio de “contenido de i18n” (llamado 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
  • Ejemplo de información de solicitud

    • Códigos de idioma: fr, en (francés y, luego, inglés)
      Los códigos de idioma se ordenan según los valores de calidad del encabezado Accept-Language.

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

Según el orden de prioridad de concordancia exacta y los valores de calidad para las preferencias de idioma, Hosting buscará en los directorios una página solicitada en el siguiente orden.

  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. Administración de páginas 404

¿Qué página se entregará al usuario?

  • Página solicitada: index.html

  • Página solicitada: awesome-page.html

Ten en cuenta la siguiente información sobre la búsqueda y entrega del directorio de “contenido de i18n”:

  • El directorio localized-files/ no contiene realmente las subcarpetas en_ca/, en_ALL/ ni en/, por lo que Hosting omitirá la lista de prioridad hasta que encuentre una subcarpeta que coincida con la combinación de idioma y país de la solicitud.

  • Si bien el directorio localized-files/ contiene una subcarpeta es_ALL/, la solicitud de ejemplo anterior no incluye un código de idioma es ni es-foo, por lo que Hosting no buscará “contenido de i18n” que coincida con es.

  • Las subcarpetas llamadas fr/ y fr_ALL/ son equivalentes desde la perspectiva de las preferencias de idioma y país de un usuario. Sin embargo, si existen ambas subcarpetas, Hosting entregará contenido en fr_ALL/ antes que en fr/.

Puedes usar cookies para anular los encabezados de idioma y país a fin de cambiar el contenido que se entrega.

A continuación, te mostramos algunas maneras de utilizar las anulaciones de cookies:

  • Prueba una función con diferentes combinaciones de idioma y país para verificar qué contenido se entrega.

  • Permite que los usuarios cambien el contenido que ven. Por ejemplo, puedes implementar un selector de idioma y, luego, establecer la cookie firebase-language-override del usuario según corresponda.

Para configurar las anulaciones de cookies, configura cookies con ambos o alguno de estos nombres: firebase-country-override y firebase-language-override. Por ejemplo, el siguiente fragmento de código de JavaScript anula el código de país para que sea ca y el encabezado Accept-Language para que sea fr,en:

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

Las anulaciones de cookies del idioma deben ser una lista de códigos de idioma separados por comas en el orden de preferencia, sin subetiquetas ni valores de calidad.

Las anulaciones de cookies no se reflejan en los registros.