Localiser une application web
Reliez les catalogues traduits aux mécanismes de sélection de langue, de chargement des ressources et de vérification du rendu de votre framework.
Si votre application web affiche déjà les messages à partir de fichiers de langue, conservez cette organisation. Lingo.dev peut traduire les catalogues source pendant que votre bibliothèque continue de choisir la langue, de charger les messages et de les afficher. Validez ce cycle complet sur un écran avant de traduire le reste de l’application.
Ce guide porte sur les catalogues à clés existants, dans différents frameworks. Pour les messages associant texte source et contexte avec @lingo.dev/react, consultez le guide de démarrage rapide React ou le guide de migration. Les identifiants extraits par cet outil diffèrent des clés d’un catalogue i18next ou next-intl existant.
Mettre en place un cas de test de bout en bout #
Choisissez un écran contenant un libellé, un message avec une variable et un message au pluriel ou conditionnel. Affichez-le dans la langue source avec la bibliothèque existante. Conservez ses espaces de noms, sa syntaxe d’interpolation et ses clés de recherche : une traduction JSON générique ne convertit pas la grammaire des messages d’une bibliothèque en celle d’une autre.
Pour une source react-i18next existante située à public/locales/en/translation.json, initialisez la CLI depuis la racine du projet :
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'public/locales/en/translation.json' --yes
lingo linkLe fichier .lingo/config.json associé doit présenter cette structure :
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es"],
"files": [{ "pattern": "public/locales/en/translation.json" }]
}Conservez les identifiants réels de l’organisation et du moteur de localisation obtenus lors de l’association. Pour un autre framework, remplacez le chemin source par celui indiqué dans les sections ci-dessous. Sélectionnez uniquement les catalogues source et alignez le chemin cible sur celui qu’utilise le chargeur. Utilisez des chemins cibles explicites pour les structures sans segment de langue.
Traduisez les cibles manquantes avec :
lingo push --backfill-missing --waitUne fois l’opération terminée, inspectez le catalogue généré et chargez l’écran en espagnol. Comparez les mêmes valeurs de variables et les mêmes cas de pluriel dans les deux langues. L’étape propre à chaque framework, décrite ci-dessous, relie ce fichier à la requête ou à la compilation effective. Un premier envoi simple peut enregistrer une version de référence sans demander les traductions manquantes.
Ne modifiez pas les cibles tant que l’écriture des résultats dans le dépôt n’a pas eu lieu. Si des corrections locales existantes doivent être protégées contre les conflits, soumettez sans --wait, inspectez lingo pull --dry-run, puis récupérez les résultats dans le checkout utilisé pour la soumission. Consultez Préserver les traductions relues.
React avec react-i18next #
Avec react-i18next, conservez vos espaces de noms et vos appels de recherche existants. Une source située à public/locales/en/translation.json correspond à public/locales/es/translation.json. Si l’application utilise plusieurs espaces de noms, configurez chaque source anglaise plutôt qu’un motif glob qui sélectionne aussi les fichiers espagnols générés.
Configurez le chargeur de ressources i18next pour qu’il demande la langue et l’espace de noms cibles. Utilisez ensuite les appels useTranslation existants pour afficher le cas de test. Vérifiez la substitution des variables et la convention des clés de pluriel utilisée par la version d’i18next installée. Un traducteur JSON générique ne convertit pas le schéma de pluriel d’une bibliothèque en celui d’une autre. Dans une application cliente, inspectez la requête réseau de chargement de la ressource ainsi que le texte affiché : le repli sur l’anglais peut masquer l’absence du fichier espagnol.
Next.js App Router avec next-intl #
Avec next-intl, la source est souvent messages/en.json, qui produit messages/es.json. Configurez la résolution de la langue au moment de la requête et chargez les messages correspondants dans votre configuration next-intl. Veillez à ce que les routes et la navigation adaptées à la langue restent cohérentes avec ce choix.
Affichez le cas de test à la fois par une requête directe dans la langue cible et en naviguant depuis une autre langue. Vérifiez le contenu rendu côté serveur, l’hydratation côté client et les variables ou pluriels ICU. Traduire le fichier de messages ne suffit pas à ajouter un segment de langue à App Router ou un sélecteur de langue. Pour les documents longs qui accompagnent ces catalogues d’interface, utilisez Markdoc avec Next.js.
Next.js Pages Router avec next-i18next #
Avec next-i18next, configurez le motif source pour qu’il corresponde à votre répertoire de langues et à vos espaces de noms existants. S’il s’agit de public/locales/en/common.json et de public/locales/en/checkout.json, traduisez les deux vers leurs équivalents espagnols. Si vous utilisez messages/en.json, conservez le chargeur personnalisé qui l’exploite réellement.
Chargez les espaces de noms requis via le mécanisme existant de chargement des données de la page, côté serveur ou lors de la génération statique. Vérifiez une requête directe vers une page localisée et un changement de route côté client. Assurez-vous que les données initiales de la page et l’environnement d’exécution client utilisent la même langue et le même espace de noms : un fichier traduit sur disque ne suffit pas si la page ne l’inclut jamais.
Vue avec vue-i18n #
vue-i18n peut charger des dictionnaires tels que src/locales/en.json et src/locales/es.json. Traduisez la source anglaise, puis enregistrez ou chargez dynamiquement le dictionnaire espagnol dans l’instance i18n existante. Définissez la langue sélectionnée là où votre application la gère déjà.
Testez les appels $t ou useI18n sur le cas de test. Vérifiez les clés imbriquées, l’interpolation et la syntaxe des messages au pluriel de la bibliothèque installée. Testez un changement de langue sans rechargement, puis un nouveau chargement de la page. Si les dictionnaires sont intégrés par des imports, vérifiez que le fichier traduit est inclus dans la compilation.
Nuxt avec le module i18n #
Avec Nuxt i18n, traduisez une source telle que locales/en.json vers locales/es.json. Enregistrez la langue et le fichier dans la configuration du module correspondant à la version installée. Alignez le répertoire de langues configuré sur le chemin de sortie de la CLI.
Suivez la stratégie de routage par langue du projet plutôt que d’en créer une seconde dans la tâche de traduction. Vérifiez le rendu côté serveur, le chargement différé, la navigation localisée et les métadonnées sur la page de test. Ajouter une cible à la configuration de traduction ne l’ajoute pas automatiquement à la liste des langues de Nuxt.
Dictionnaires Svelte et SvelteKit #
Avec svelte-i18n, traduisez un dictionnaire tel que src/lib/locales/en.json. Enregistrez le dictionnaire cible ou son chargeur différé et initialisez la langue sélectionnée avant que le composant en ait besoin.
Affichez le cas de test via le magasin de traduction existant de l’application. Testez une nouvelle requête avec rendu côté serveur si l’application utilise le SSR, puis un changement de langue côté client. Vérifiez que l’état de la langue reste isolé entre les requêtes serveur et que le chargement du dictionnaire cible arrive à son terme. Ne prenez pas le texte de repli comme preuve que la traduction est terminée.
XLIFF avec Angular #
Utilisez d’abord le workflow i18n d’Angular pour marquer et extraire les messages. Le gestionnaire XLIFF prend en charge XLIFF 1.2 et 2.x, y compris le texte brut et les codes intégrés. Le texte contenu dans des codes appariés tels que <g> et <pc> est traduit, tandis que leur structure est conservée ; les codes autonomes tels que <ph> restent protégés. Conservez des identifiants stables pour les messages et les codes intégrés, puis inspectez les espaces réservés renvoyés avant d’importer le catalogue cible.
Pour les entrées prises en charge, src/locale/en/messages.xlf correspond à src/locale/es/messages.xlf. XLIFF n’utilise pas la substitution de suffixe de messages.en.xlf vers messages.es.xlf : utilisez le répertoire de langue ou un modèle de chemin cible explicite. Préservez les identifiants des messages lorsque vous réintégrez les traductions dans Angular.
Enregistrez le fichier cible dans la configuration de compilation pour la localisation d’Angular, compilez le paquet de la langue cible et servez-le pour inspecter l’écran. La localisation d’Angular à la compilation diffère du chargement de fichiers JSON à l’exécution : changer la langue du navigateur ne génère pas un paquet localisé manquant. Vérifiez la couverture des messages et le rendu des espaces réservés avant d’accepter le paquet.
Astro #
Pour les libellés d’interface, traduisez src/i18n/en.json vers son équivalent cible et configurez votre propre chargeur de dictionnaires pour qu’il le sélectionne. Pour les collections de contenu, traduisez les sources Markdown ou MDX propres à chaque langue et utilisez le workflow de contenu statique.
Configurez le routage par langue d’Astro indépendamment de la traduction. Compilez et consultez les routes cibles générées. Vérifiez les liens entre les versions linguistiques ainsi que les éventuels îlots côté client qui chargent leurs propres messages. Une collection de contenu et le dictionnaire d’interface d’un îlot peuvent nécessiter des entrées distinctes.
Laravel #
Pour la localisation avec Laravel, une source PHP telle que lang/en/messages.php correspond à lang/es/messages.php. Préservez les clés de tableau et les noms des paramètres remplacés à l’exécution. Consultez la référence du format PHP avant de sélectionner des fichiers contenant du code exécutable qui dépasse la structure de catalogue prise en charge.
Définissez la langue de la requête via le middleware existant de l’application ou les règles du contrôleur, puis affichez les messages à l’aide des fonctions de traduction de Laravel. Testez les valeurs de remplacement et la sélection du pluriel. Testez une requête dans chaque langue prise en charge ainsi qu’un cas de repli : les fichiers traduits ne choisissent pas la langue de la requête.
Django #
Utilisez le workflow d’extraction de Django pour créer locale/en/LC_MESSAGES/django.po, puis traduisez ce fichier PO source dans le répertoire de la langue cible. Préservez les identifiants des messages gettext, leur contexte et leur interpolation. À l’aide de l’étape de compilation gettext existante du projet, compilez le PO traduit pour obtenir la ressource que Django charge réellement.
Configurez la sélection de langue de Django et la liste des langues. Vérifiez une requête localisée via le middleware de traduction et affichez les messages issus des appels au singulier et au pluriel. La présence d’un fichier PO sur disque ne prouve pas que son catalogue compilé est à jour. Consultez Gettext pour les exigences du format de fichier.
Rails #
Rails reconnaît les fichiers YAML organisés par langue à partir de leur clé racine. Sélectionnez yaml-root-key, puis vérifiez la configuration des langues de Rails, ses fonctions utilitaires et l’interpolation. Le guide Localiser une application Rails détaille la procédure complète, notamment les fichiers par domaine fonctionnel, le changement de langue des requêtes et les mises à jour ciblées.
Produire des traductions récurrentes prêtes pour la relecture #
Une fois l’écran fonctionnel, ajoutez les catalogues source restants et leurs chargeurs. Conservez les cibles acceptées avec la révision source et le Lockfile de la CLI. Pour les modifications ultérieures de la source, utilisez lingo push --wait pour le traitement habituel des différences ; un motif de fichiers passé en argument positionnel sélectionne plutôt une planification ciblée.
Choisissez les déclencheurs liés aux modifications des sources et le mode d’écriture des résultats dans le dépôt via la GitHub App ou les recettes CI. Les recettes GitLab, Bitbucket et GitHub Actions exécutent la CLI et doivent gérer leur propre écriture des résultats dans le dépôt. Compilez les résultats avec le framework ou exécutez ses vérifications de ressources, puis relisez les traductions pour en vérifier le sens. lingo check ne valide pas tous les frameworks et ne garantit pas l’exhaustivité des fichiers PHP, PO ou XLIFF.
Un agent peut vous aider à inspecter les chargeurs et à proposer des modifications de configuration. Soumettez ces modifications aux mêmes vérifications de sélection des sources, de compilation et de rendu à l’écran avant d’étendre le workflow.