Configurer les réécritures d'internationalisation (i18n)

Utilisez les réécritures d'internationalisation ("réécritures i18n") pour diffuser différents contenus en fonction du pays ou de la langue préférée d'un utilisateur. Voici quelques exemples de configurations que vous pouvez définir :

  • Diffuser le même contenu en français à tous les utilisateurs qui préfèrent le français (quel que soit le pays)
    Exemple : page d'accueil avec du texte en français

  • Diffuser du contenu en français standard aux utilisateurs qui préfèrent le français, mais diffuser du contenu en français canadien aux utilisateursqui préfèrent le français.
    Exemple : une page d'accueil avec des expressions en français standard par rapport à une page d'accueil avec des expressions en français canadien

  • Diffuser le même contenu à tous les utilisateurs canadiens (quelle que soit leur langue préférée)
    Exemple : une page d'accueil dans la langue "par défaut" de votre site, mais avec une fonctionnalité spécifique au Canada (comme un thème de vacances)

  • Diffuser du contenu en français canadien aux utilisateurs canadiens qui préfèrent le français.
    Exemple : une page d'accueil avec des expressions en français canadien et une fonctionnalité spécifique au Canada (comme un thème de fête)

Firebase Hosting détermine le pays d'un utilisateur à partir de son adresse IP et ses préférences linguistiques à partir de l'en-tête de requête Accept-Language (généralement défini automatiquement par son navigateur Web).

Configurer les réécritures i18n

Pour configurer les réécritures i18n pour votre site Hosting, vous devez créer un répertoire "i18n content" pour tous vos contenus traduits, puis ajouter l'attribut i18n à votre fichier firebase.json pour pointer vers votre nouveau répertoire "i18n content".

Voici la procédure détaillée :

  1. Dans le dossier public du répertoire local de votre application, créez un répertoire distinct pour votre "contenu i18n", puis créez des sous-dossiers pour chaque combinaison de langue et de pays acceptée par votre site.

    Dans chaque sous-dossier, ajoutez le contenu spécifique à cette combinaison, comme des pages d'accueil sur le thème des fêtes ou des pages 404 spécifiques à une langue.

    Voici un exemple de répertoire de contenu i18n appelé 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

    Le répertoire localized-files/ contient des sous-dossiers distincts pour chaque combinaison de langue et de pays acceptée par votre site. Le modèle de dénomination de chaque sous-dossier doit respecter l'un des formats suivants :

    • languageCode_countryCode : contient du contenu spécifique aux utilisateurs qui ont cette préférence de langue et ce code pays.

    • languageCode : contient du contenu spécifique aux utilisateurs qui ont cette préférence linguistique, mais le contenu n'est pas spécifique à un pays. Il est donc équivalent à languageCode_ALL.

    Pour en savoir plus sur ces codes, consultez la sous-section Codes de pays et de langue ci-dessous. Vous pouvez utiliser la valeur ALL (sensible à la casse) pour indiquer n'importe quel pays (comme es_ALL/) ou n'importe quelle langue (comme ALL_ca/).

    Les fichiers d'un sous-dossier n'ont pas besoin d'avoir des fichiers analogues dans le répertoire public ou dans d'autres sous-dossiers. Vous pouvez créer du contenu entièrement spécifique à une langue et/ou à un pays.

  2. Ajoutez l'attribut i18n à votre fichier firebase.json et spécifiez le répertoire contenant votre "contenu i18n". Reprenons notre exemple :

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

    Le répertoire spécifié pour root doit être le nom du répertoire contenant tous vos sous-dossiers de contenu i18n. Si vous avez placé tous vos sous-dossiers de "contenu i18n" à la racine de votre répertoire public, utilisez / pour la valeur de root. Les barres obliques de début et de fin dans la valeur root sont facultatives.

  3. Déployez votre contenu et votre configuration "i18n" sur votre site Hosting.

Vous pouvez tester votre configuration à l'aide des remplacements de cookies.

Codes pays et de langue

Lorsque vous nommez des sous-dossiers de "contenu i18n", vous devez utiliser des minuscules pour les codes de pays et de langue. Vous pouvez utiliser la valeur ALL (sensible à la casse) pour indiquer n'importe quel pays (comme es_ALL/) ou n'importe quelle langue (comme ALL_ca/).

Hosting obtient le code pays à partir de l'adresse IP de l'utilisateur. Les codes pays sont des codes ISO 3166-1 alpha-2 à deux lettres.

Les codes de langue sont obtenus à partir de l'en-tête de requête Accept-Language de l'utilisateur (généralement défini automatiquement par son navigateur Web). Il s'agit de codes ISO 639-1. Tenez compte des points suivants lorsque vous utilisez des codes de langue :

  • Lorsque Hosting recherche le "contenu i18n" à diffuser, il ordonne les langues en fonction des valeurs de qualité dans l'en-tête Accept-Language.

  • Hosting supprime tous les sous-tags régionaux et de pays dans l'en-tête Accept-Language. Par conséquent, le code de langue dans le nom d'un sous-dossier "i18n content" ne peut pas contenir ces sous-tags. Par exemple, vous ne pouvez pas utiliser es-419 ou es-US comme code de langue dans le nom d'un sous-dossier, mais vous pouvez utiliser es.

    Si vous souhaitez diffuser du contenu spécifique à une région ou à un pays, vous pouvez créer des sous-dossiers contenant le contenu spécifique à la langue et au pays que vous souhaitez prendre en charge.

Ordre de priorité pour le "contenu i18n"

Si vous configurez des réécritures i18n, Hosting diffuse le contenu en fonction de l'ordre de priorité suivant :

  1. Espaces de noms réservés commençant par un segment de chemin d'accès /__/*

  2. Redirections configurées

  3. Contenu statique en correspondance exacte

    1. Code de langue + code pays (par exemple, contenu de fr_ca/)
      L'ordre suit les valeurs de qualité pour chaque langue dans l'en-tête Accept-Language de la requête.

    2. Code pays uniquement (par exemple, contenu provenant de ALL_ca/)

    3. Code de langue uniquement (par exemple, contenu de fr/ ou es_ALL/)
      L'ordre suit les valeurs de qualité pour chaque langue dans l'en-tête Accept-Language de la requête.

    4. Contenu statique par défaut en correspondance exacte
      Il s'agit du contenu qui se trouve en dehors du répertoire "i18n content", par exemple à la racine du répertoire public.

  4. Réécritures configurées

  5. Gestion des erreurs 404

    1. Pages 404 i18n
      L'ordre de priorité est le même que celui indiqué ci-dessus pour le contenu statique en correspondance exacte.

    2. Page 404 personnalisée

    3. Page 404 par défaut (fournie par Firebase)

Exemple d'ordre de priorité

Reprenons l'exemple ci-dessus. Nous allons utiliser le même répertoire d'exemple et une requête d'exemple.

  • Exemple de répertoire de projet local avec un répertoire "i18n content" (appelé 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
  • Exemple d'informations sur une demande

    • Codes de langue : fr, en (français, puis anglais)
      Les codes de langue sont classés en fonction des valeurs de qualité dans l'en-tête Accept-Language.

    • Code pays : ca (Canada)

Selon l'ordre de priorité de la correspondance exacte et les valeurs de qualité pour les préférences linguistiques, Hosting recherche la page demandée dans les répertoires dans l'ordre suivant.

  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. Gestion des erreurs 404

Quelle page sera présentée à l'utilisateur ?

  • Page demandée : index.html

  • Page demandée : awesome-page.html

Notez les points suivants concernant la recherche et la diffusion du répertoire "i18n content" :

  • Le répertoire localized-files/ ne contient pas réellement les sous-dossiers en_ca/, en_ALL/ ni en/. Hosting passera donc à la liste des priorités jusqu'à ce qu'il trouve un sous-dossier correspondant à la combinaison langue/pays de la requête.

  • Même si le répertoire localized-files/ contient un sous-dossier es_ALL/, l'exemple de requête ci-dessus n'inclut pas de code de langue es ni es-foo. Par conséquent, Hosting ne recherchera pas de "contenu i18n" correspondant à es.

  • Les sous-dossiers fr/ et fr_ALL/ sont équivalents du point de vue des préférences de l'utilisateur concernant le pays et la langue. Toutefois, si les deux sous-dossiers existent, Hosting diffusera le contenu fr_ALL/ avant le contenu fr/.

Vous pouvez modifier le contenu diffusé en utilisant des cookies pour remplacer les en-têtes de pays et de langue.

Voici quelques exemples d'utilisation des remplacements de cookies :

  • Testez une fonctionnalité avec différentes combinaisons de langues et de pays pour vérifier le contenu diffusé.

  • Permettez à vos utilisateurs de modifier le contenu qu'ils voient. Par exemple, vous pouvez implémenter un sélecteur de langue, puis définir le cookie firebase-language-override de l'utilisateur en conséquence.

Pour configurer des remplacements de cookies, définissez des cookies avec l'un ou l'autre de ces noms : firebase-country-override et firebase-language-override. Par exemple, l'extrait de code JavaScript suivant remplace le code pays par ca et l'en-tête Accept-Language par fr,en :

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

Les substitutions de cookie de langue doivent être une liste de codes de langue séparés par une virgule, par ordre de préférence, sans sous-balises ni valeurs de qualité.

Les remplacements de cookies ne sont pas reflétés dans les journaux.