Chaînes d'interface utilisateur

Conçu pour tout projet JS/TS qui utilise i18next : applications React, Next.js (composants client et serveur), services Node.js, HTML simple, sites web Astro et outils CLI.

Quel guide lire

Votre application	Lire la suite
React / Next.js / Node + i18next	Connecter i18next (Étape 4)
HTML simple (pas de t() dans le balisage)	Applications HTML simples
Site marketing Astro (hybride)	Site web Astro
Règles t(), interpolation, pluriels	Appels t() et pluriels
Sélecteur de langue / RTL	Sélecteur de langue et RTL
Signatures d'API d'exécution	Aides d'exécution

Étape 1 : Initialiser

ai-i18n-tools init [-P <provider>]

Ceci écrit ai-i18n-tools.config.json avec le modèle ui-markdown (incluant un bloc provider / providers par défaut). Avant d'exécuter translate-ui ou sync, définissez la clé API de votre fournisseur actif dans l'environnement ou .env — Ollama excepté ; voir Fournisseur et clé API. Modifiez la configuration pour définir :

• provider et providers — au moins un fournisseur avec translationModels ; modifiez le préréglage ou la liste de modèles si la valeur par défaut ne vous convient pas (init -P <provider>). Voir Fournisseurs et modèles LLM.
• sourceLocale - votre code BCP-47 de langue source (par exemple "en-GB"). Doit correspondre à SOURCE_LOCALE exporté depuis votre fichier de configuration i18n d'exécution (src/i18n.ts / src/i18n.js).
• targetLocales - tableau de codes BCP-47 pour vos langues cibles (par exemple ["de", "fr", "pt-BR"]). Exécutez generate-ui-languages pour créer le manifeste ui-languages.json à partir de cette liste.
• ui.sourceRoots - répertoires ou modèles glob à analyser pour les appels t("…") (par exemple ["src/"], ["src/**/*.ts"]).
• ui.stringsJson - où écrire le catalogue maître (par exemple "src/locales/strings.json").
• ui.flatOutputDir - où écrire de.json, pt-BR.json, etc. (par exemple "src/locales/").
• providers.<active>.uiModels (facultatif) - liste ordonnée de modèles UI uniquement pour translate-ui, la génération de pluriels et proofread-ui (après toute entrée localeModels correspondante, avant translationModels). Voir Fournisseurs et modèles.

Étape 2 : Extraire les chaînes

ai-i18n-tools extract

Analyse tous les fichiers JS/TS situés dans ui.sourceRoots à la recherche des appels t("literal") et i18n.t("literal"). Écrit (ou fusionne dans) ui.stringsJson.

Le scanner est configurable : ajoutez des noms de fonctions personnalisés via ui.uiExtractor.funcNames (ou l'ancien ui.reactExtractor.funcNames). Pour les pages et composants Astro, ajoutez .astro à ui.uiExtractor.extensions. Pour le HTML simple, voir Applications HTML simples.

Étape 3 : Traduire les chaînes de l'interface utilisateur

ai-i18n-tools translate-ui

Lit strings.json, envoie des lots au fournisseur LLM actif pour chaque locale cible, écrit des fichiers JSON plats (de.json, fr.json, etc.) dans ui.flatOutputDir. La sélection du modèle utilise la chaîne de l'interface utilisateur : localeModels(locale) → uiModels → translationModels (voir Fournisseurs et modèles).

Substitutions de modèle par locale

Selon la langue cible, certains modèles de traduction peuvent être significativement plus performants que d'autres — par exemple, les modèles qwen et z-ai ont tendance à produire des traductions de meilleure qualité pour les langues asiatiques par rapport à de nombreux modèles de langues occidentales. Pour en tirer parti, vous pouvez utiliser des entrées providers.<active>.localeModels facultatives pour spécifier une liste priorisée de modèles pour chaque locale BCP-47. Ces listes de modèles sont essayées avant les uiModels et translationModels plus généraux pour cette locale particulière. Cela vous permet d'adapter la sélection des modèles et d'obtenir une meilleure qualité de traduction par langue. Les balises de locale sont mises en correspondance sans tenir compte de la casse (donc zh-cn et ZH-CN sont équivalents). Si aucune entrée personnalisée ne correspond à une locale, l'outil revient à l'ordre par défaut uiModels et translationModels pour les traductions d'interface utilisateur. Le même mécanisme localeModels s'applique également à la traduction de documents, JSON et SVG.

Base de données des traductions (strings.json)

Pour chaque entrée, translate-ui stocke l'ID du modèle du fournisseur actif qui a traduit avec succès chaque locale dans un objet models facultatif (mêmes clés de locale que translated). Les chaînes éditées dans le tableau de bord de traduction sont marquées avec la valeur sentinelle user-edited dans models pour cette locale. Les fichiers plats par locale sous ui.flatOutputDir restent uniquement chaîne source → traduction ; ils n'incluent pas models (ainsi les bundles d'exécution restent inchangés).

Remarque : Les modifications du tableau de bord apportées aux chaînes de l'interface utilisateur se trouvent dans strings.json, et non dans le cache de documentation SQLite. Exécutez simplement sync ou translate-ui (sans indicateur spécial) pour réécrire les fichiers de locale plats à partir du catalogue — --force-update n'est pas transmis à l'étape de l'interface utilisateur. Évitez --force sur les commandes de l'interface utilisateur après des modifications manuelles : cela retraduit chaque entrée et peut écraser vos lignes user-edited.

Ensuite, connectez i18next à l'exécution — Connecter i18next.

Exportation vers XLIFF 2.0 (facultatif)

Pour transmettre les chaînes d'interface à un prestataire de traduction, un système de gestion de la traduction (TMS) ou un outil CAT, exportez le catalogue au format XLIFF 2.0 (un fichier par langue cible). Cette commande est en lecture seule : elle ne modifie pas strings.json ni n'appelle aucune API.

ai-i18n-tools export-ui-xliff

Par défaut, les fichiers sont écrits à côté de ui.stringsJson, avec des noms comme strings.de.xliff, strings.pt-BR.xliff (nom de base de votre catalogue + langue + .xliff). Utilisez -o / --output-dir pour écrire ailleurs. Les traductions existantes provenant de strings.json apparaissent dans <target> ; les langues manquantes utilisent state="initial" sans <target>, afin que les outils puissent les compléter. Utilisez --untranslated-only pour n'exporter que les unités nécessitant encore une traduction pour chaque langue (pratique pour les lots envoyés aux prestataires). --dry-run affiche les chemins sans écrire les fichiers.