Démarrage rapide
Cette page guide un projet monolingue vers ses premiers fichiers traduits. Elle s'adresse à une application JS/TS, une application Python, une application .NET, un site web ou un site de documentation, ou un fichier README de dépôt et d'autres fichiers Markdown. Elle suppose :
- Node.js
>=22.16.0, ou l'exécutable autonome pour un projet Python ou .NET. - Une clé API pour un fournisseur de LLM, ou une installation locale d'Ollama.
- Le projet est sous contrôle de version, afin que vous puissiez examiner ce que l'outil écrit.
Deux choses diffèrent entre les projets : la façon dont l'outil trouve votre texte, et la façon dont votre application charge le résultat. Choisissez votre chemin ci-dessous vous envoie vers le bon guide pour cela.
Exemples exécutables
Vous préférez d'abord consulter un projet terminé ? Copiez-en un sans cloner le dépôt :
npx degit wsj-br/ai-i18n-tools/examples/console-app console-app
cd console-app
pnpm install
pnpm run i18n:syncRemplacez console-app par tout autre exemple Node.js. Les exemples Python et .NET n'ont pas de package.json ; copiez-les de la même manière. Les quatre exemples Python se trouvent également dans ai-i18n-tools-python-examples.zip sur la version GitHub, et les deux exemples .NET se trouvent dans ai-i18n-tools-dotnet-examples.zip. La liste complète, avec ce que chacun montre, se trouve sur la page Exemples.
Installer
pnpm add -D ai-i18n-toolsnpm install --save-dev ai-i18n-tools et yarn add --dev ai-i18n-tools fonctionnent aussi. Les projets Python et .NET installent l'exécutable autonome et n'ont pas besoin de Node.js. Linux et macOS : curl -fsSL https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.sh | bash. Windows PowerShell : irm https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.ps1 | iex. Autres options d'installation : Installation.
Fournisseur et clé API
Chaque commande qui appelle un LLM (translate-ui, translate-docs, translate-json, translate-svg et sync) nécessite ces deux éléments :
- Au moins un fournisseur dans
ai-i18n-tools.config.json: un blocproviders.<name>avectranslationModels, et une cléproviderde niveau supérieur lorsque plusieurs fournisseurs sont configurés.init -P <provider>génère ce préréglage. Pour ajouter des fournisseurs, consultez Fournisseurs de LLM. Pour choisir la liste des modèles, consultez Modèles d'IA. - La clé API correspondante dans votre environnement, ou dans
.env/.env.localà côté deai-i18n-tools.config.jsonlorsqu'aucune clé API de fournisseur n'est déjà définie. Chaque préréglage intégré lit une variable nommée à partir du tableau des préréglages, par exempleOPENROUTER_API_KEYavec-P openrouterouOPENAI_API_KEYavec-P openai. Ollama utilise un point de terminaison local et n'a pas besoin de clé.
export OPENROUTER_API_KEY=sk-or-v1-your-key-hereextract, status et les autres commandes qui n'appellent pas le LLM n'ont besoin d'aucun des deux. Plus d'informations sur les fichiers d'environnement et le PATH : Installation.
Choisissez votre chemin
Trouvez ce que vous avez, exécutez les commandes de son bloc, puis continuez dans le guide lié.
Une application JS/TS
Vos boutons et messages sont encore en texte brut dans la source, l'outil n'a donc rien à trouver pour l'instant. Ils doivent d'abord être enveloppés dans t(), et l'application a besoin d'un petit fichier de configuration i18next.
ai-i18n-tools init -P openrouter
ai-i18n-tools suggest-models --applySuivez ensuite Ajouter l'i18n à une application JS/TS. Il couvre l'étape d'encapsulation, avec une invite d'agent, avant extract et translate-ui.
Une application Python
ai-i18n-tools init -t ui-python -P openrouter
ai-i18n-tools suggest-models --applySuivez ensuite Ajouter l'i18n à une application Python.
Une application Django, Flask avec des catalogues Flask-Babel, ou une application qui appelle déjà gettext conserve ces appels. Générez avec ui-python-django, ui-python-flask ou ui-python-gettext à la place, puis suivez Ajouter l'i18n à une application Django / Python gettext.
Une application .NET
ai-i18n-tools init -t ui-dotnet -P openrouter
ai-i18n-tools suggest-models --applySuivez ensuite Ajouter l'i18n à une application .NET. Une application qui utilise déjà ResourceManager ou IStringLocalizer utilise ui-dotnet-resx à la place, puis Ajouter l'i18n à une application .NET ResourceManager. migrate-dotnet-i18n réécrit T($"…") en appels {0} numérotés. --wrap audite les étiquettes XAML et C# non marquées. Le rapport liste les clés resx nommées, telles que Resources.LoginButton, comme suggestions et ne modifie pas ces lignes.
Un site web ou un site de documentation
Choisissez le modèle pour votre framework :
| Votre site | Modèle |
|---|---|
| Astro Starlight | ui-starlight |
| Docusaurus | ui-docusaurus |
| VitePress | ui-vitepress |
| Nextra | ui-nextra |
| Fumadocs | ui-fumadocs |
| Site web Astro simple | ui-astro-website |
| Pages HTML simples | ui-plain-html ou docs-plain-html |
ai-i18n-tools init -t ui-vitepress -P openrouterSuivez ensuite Ajouter l'i18n à un site web ou un site de documentation. Son invite d'agent active le routage i18n du framework. Vous exécutez sync après avoir examiné ce travail.
Un README ou de la documentation Markdown
La plupart des dépôts souhaitent cela avec l'application : le modèle ui-markdown par défaut inclut déjà un bloc README plat. Pour tout autre modèle, ajoutez --with-readme. Un dépôt contenant uniquement du Markdown utilise docs-markdown.
ai-i18n-tools init -P openrouter
ai-i18n-tools init -t ui-python -P openrouter --with-readme
ai-i18n-tools init -t ui-dotnet -P openrouter --with-readme
ai-i18n-tools init -t docs-markdown -P openrouterSuivez ensuite Ajouter l'i18n à votre README et aux documents Markdown. Collez le marqueur de liste de langues dans README.md avant sync. Le chemin de l'application, si vous en avez un, est toujours Ajouter l'i18n à une application JS/TS, Ajouter l'i18n à une application Python, ou Ajouter l'i18n à une application .NET.
Autre chose
- JSON i18next imbriqué qui reste tel quel :
ai-i18n-tools init -t ui-json-bundles -P openrouter, puis JSON. - Diagrammes SVG avec étiquettes de texte : Traduction SVG.
- Abandonner Intlayer : Migration depuis Intlayer.
- Conserver Intlayer et ne remplir que ses traductions : Traduire Intlayer sur place.
La liste complète des modèles, avec chaque option init, se trouve dans la référence de configuration CLI.
Exécuter et vérifier
Lorsque votre projet est prêt :
ai-i18n-tools doctor
ai-i18n-tools sync
ai-i18n-tools statusdoctor vérifie que la configuration, les chemins, les fournisseurs et l'environnement sont prêts. Il vérifie également les identifiants de modèle avec le fournisseur, sauf si vous passez --local. sync exécute chaque étape activée par votre configuration, dans l'ordre. status affiche ce qui est traduit par locale. Une première exécution sur un projet où l'outil ne peut pas voir de texte se termine sans erreur et n'écrit rien d'utile, donc si status n'affiche aucune chaîne, revenez au guide correspondant à votre chemin.
suggest-models classe les modèles de chat du fournisseur actif à partir de benchmarks publiés. suggest-models --apply remplace translationModels et ne modifie pas uiModels et localeModels. Le même classement se trouve dans l'onglet Modèles du tableau de bord. Fonctionnement du classement et pourquoi la liste contient plusieurs modèles : Modèles d'IA. Référence de la commande : suggest-models.
Maintenir la traduction
Réexécutez sync chaque fois que le texte source change. Un cache SQLite signifie que seul le texte nouveau ou modifié est envoyé au modèle, donc les réexécutions sont peu coûteuses. L'exécution de sync en CI empêche les traductions de dériver. ai-i18n-tools dashboard ouvre le Tableau de bord de traduction pour examiner et modifier les traductions mises en cache.
Scripts package.json recommandés
Avec le package installé localement, les scripts résolvent ai-i18n-tools depuis node_modules/.bin sans configuration de shell supplémentaire. Pour un shell interactif, configurez d'abord le PATH : consultez Utilisation de la CLI.
{
"i18n:extract": "ai-i18n-tools extract",
"i18n:sync": "ai-i18n-tools sync",
"i18n:translate:ui": "ai-i18n-tools translate-ui",
"i18n:translate:svg": "ai-i18n-tools translate-svg",
"i18n:translate:docs": "ai-i18n-tools translate-docs",
"i18n:translate:json": "ai-i18n-tools translate-json",
"i18n:status": "ai-i18n-tools status",
"i18n:statistics": "ai-i18n-tools statistics",
"i18n:dashboard": "ai-i18n-tools dashboard",
"i18n:cleanup": "ai-i18n-tools cleanup"
}Préférez sync à l'enchaînement des scripts de traduction individuels. N'utilisez les scripts à étape unique que si vous avez besoin d'une seule étape de manière isolée.
Pour afficher la sortie de la CLI et le tableau de bord dans une autre langue, passez -L <code> ou définissez AI_I18N_LANG : voir Langue de l'interface utilisateur de l'outil.
Vous traduisez plusieurs types de contenu, comme des chaînes d'application et un site de documentation ensemble ? Consultez Combinaison de pipelines.
Suivant : le guide correspondant à votre parcours sous Choisissez votre parcours.