Chaînes d'interface utilisateur
Référence pour extract et translate-ui, le pipeline qui transforme les appels t() en catalogues par locale. Vous ajoutez l'i18n à une application pour la première fois ? Commencez par Ajouter l'i18n à une application JS/TS, Ajouter l'i18n à une application Python ou Ajouter l'i18n à une application .NET. Ils couvrent l'étape d'encapsulation, puis vous renvoient ici pour les étapes 2 à 4.
Ce pipeline prend en charge les projets JS/TS (composants client et serveur React, Next.js, services Node.js, HTML simple, sites web Astro et outils CLI), les applications Python et les applications .NET. JS/TS recherche les chaînes avec i18next après que la source appelle t(). Python appelle t() ou gettext via un i18n.py généré (Django conserve le gettext de Django). .NET appelle T() via un I18n.cs généré.
Quel guide lire
| Votre application | Lire ensuite |
|---|---|
JS/TS avec des chaînes de caractères codées en dur, pas encore de t() | Ajouter l'i18n à une application JS/TS |
React / Next.js / Node, t() déjà dans le code source | Connecter i18next |
Python (t(), _(), gettext, Jinja, Django) | Applications Python. Initialisation : ui-python, ui-python-gettext, ui-python-flask, ou ui-python-django. Assistant : i18n.py. Pour ajouter des locales à une application existante, voir Ajouter l'i18n à une application Python, ou Ajouter l'i18n à une application Django / Python gettext lorsque l'application utilise gettext. |
.NET (T(), Tn, Tp, XAML loc:Tr) | .NET applications. Initialisation : ui-dotnet (I18n.cs) ou ui-dotnet-resx (Ajouter l'i18n à une application .NET ResourceManager). Pour ajouter des locales à une application existante, voir Ajouter l'i18n à une application .NET. |
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 |
Dictionnaires Intlayer .content.ts, migration d'Intlayer | Migration depuis Intlayer |
Dictionnaires Intlayer .content.ts, conserver Intlayer | Traduire Intlayer sur place |
Étape 1 : Initialiser
ai-i18n-tools init -P openrouterCeci écrit ai-i18n-tools.config.json avec le modèle ui-markdown (y compris le bloc provider / providers pour ce préréglage). Ce modèle active également la traduction de documents pour README.md, écrits sous forme de fichiers plats sous translated-docs/. Les dépôts contenant uniquement un README utilisent init -t docs-markdown à la place. Voir Ajouter l'i18n à votre README et à vos documents Markdown. Avant d'exécuter translate-ui ou sync, définissez la clé API de ce fournisseur dans l'environnement ou .env — sauf Ollama ; voir Fournisseur et clé API. Quatre clés sont importantes pour les chaînes d'interface utilisateur :
sourceLocale: le code BCP-47 de la langue dans laquelle votre texte source est écrit. Toute langue est valide ;"en-GB"n'est qu'un exemple. Il doit correspondre àSOURCE_LOCALEexporté depuis votre fichier de configuration i18n d'exécution (src/i18n.ts/src/i18n.js). La chaîne à l'intérieur det()est cette langue source, et les fichiers de locale plats l'utilisent comme clé.targetLocales: codes BCP-47 pour vos langues cibles (par exemple["de", "fr", "pt-BR"]). Exécutezgenerate-ui-languagespour créer le manifesteui-languages.jsonà partir de cette liste.ui.sourceRoots: répertoires ou motifs glob à analyser pour les appelst("…")(par exemple["src/"]).ui.stringsJsonetui.flatOutputDir: où le catalogue maître et les fichiers par locale (de.json,pt-BR.json) sont écrits.
Toutes les autres clés, y compris providers.<active>.uiModels, se trouvent dans Configuration.
Étape 2 : Extraire les chaînes
extract ne fait rien d'utile tant que ces appels t() / i18n.t() n'existent pas. Encapsulez d'abord le texte codé en dur : Ajouter l'i18n à une application JS/TS.
ai-i18n-tools extractAnalyse les fichiers sous ui.sourceRoots pour les 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.
Qu'est-ce que les scans d'extraction
- Les extensions par défaut sont uniquement
.js,.jsx,.tset.tsx..mjs,.cjs,.mtset.ctsne sont incluses que si vous les ajoutez àui.uiExtractor.extensions. - Une clé non littérale telle que
t(variable)ou un littéral de gabarit est ignorée sans avertissement. package.jsondescriptionest inclus par défaut (ui.uiExtractor.includePackageDescription).- Les composants monofichiers Vue et Svelte ne sont pas pris en charge. L'ajout de
.vueou.svelteàextensionsn'extrait pas le texte du modèle. Il n'y a pas d'analyseur SFC.
Étape 3 : Traduire les chaînes de l'interface utilisateur
ai-i18n-tools translate-uiLit strings.json, envoie des lots aux modèles sur le fournisseur LLM actif pour chaque locale cible, écrit des fichiers JSON plats (de.json, fr.json, etc.) vers ui.flatOutputDir. La sélection du modèle utilise la chaîne d'interface utilisateur : localeModels(locale) → uiModels → translationModels (voir Modèles d'IA). Dans une locale, jusqu'à uiBatchConcurrency lots s'exécutent simultanément (par défaut 2 ; voir Configuration — uiBatchConcurrency). -j ne parallélise toujours que les locales cibles. Chaque lot réussi est écrit dans strings.json et le fichier de locale plat avant le démarrage du lot suivant, ainsi, l'arrêt de l'exécution ou une erreur d'API ultérieure conserve les lots déjà terminés.
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 aux chaînes d'interface utilisateur résident dans
strings.json, et non dans le cache de documentation SQLite. Exécutez simplementsyncoutranslate-ui(sans drapeau spécial) pour réécrire les fichiers de locale plats à partir du catalogue —--force-updaten'est pas transmis à l'étape de l'interface utilisateur. Évitez--forcesur les commandes d'interface utilisateur après des modifications manuelles : cela re-traduit chaque entrée et peut écraser vos lignesuser-edited. Les lignes du catalogue dont la traduction stockée échoue à la vérification du système d'écriture de la locale (par exemple, l'hindi romanisé pourhi) sont traitées comme manquantes et re-traduites sans--force.
Étape 4 : Utiliser la sortie dans votre application
translate-ui écrit uniquement des fichiers. L'application doit les charger.
- JS/TS : configurez i18next avec les assistants d'exécution, chargez le fichier de locale choisi par l'utilisateur et ajoutez un sélecteur de langue. Voir Configurer i18next et Sélecteur de langue et RTL.
- Python : utilisez le
i18n.pygénéré ou vos catalogues gettext. Voir Applications Python. - .NET : utilisez le
I18n.csgénéré, ouI18nResx.cslorsque l'application utilise déjàResourceManager. Voir Applications .NET et Ajouter l'i18n à une application .NET ResourceManager.migrate-dotnet-i18nréécrit les argumentsT()non sécurisés.--wrapaudite les étiquettes non marquées. - HTML simple : chargez le script d'exécution à côté de la page. Voir Applications HTML simples.
- Astro : voir Site web Astro.
Facultatif
Substitutions de modèle par locale
Certains modèles traduisent mieux certaines langues que d'autres. Par exemple, les modèles qwen et z-ai ont tendance à bien fonctionner avec les langues asiatiques. Ajoutez des entrées providers.<active>.localeModels pour fournir une liste de modèles priorisée pour chaque locale BCP-47. Ces listes sont essayées avant uiModels et translationModels pour cette locale. Les balises de locale correspondent sans tenir compte de la casse (zh-cn et ZH-CN sont équivalentes). Sans entrée correspondante, l'outil utilise l'ordre par défaut uiModels et translationModels. Le même mécanisme localeModels s'applique à la traduction de documents, JSON et SVG.
Exportation vers XLIFF 2.0
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-xliffPar 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.