JSON
À qui s'adresse ceci : les projets qui conservent déjà leur contenu dans des fichiers JSON imbriqués par locale (par exemple src/i18n/en/translation.json) et souhaitent conserver cette structure. Si votre source contient du texte brut et n'a pas encore de t(), commencez plutôt par Ajouter l'i18n à une application JS/TS.
Le CLI parcourt les valeurs de chaîne dans ces fichiers, les traduit avec les modèles du fournisseur LLM actif et écrit les sorties par paramètres régionaux à l'aide de json[].outputPathTemplate. Il utilise le même cache SQLite que translate-docs et translate-svg (cacheDir).
Ce pipeline n'exécute pas extract — il n'y a pas de catalogue strings.json. Activez-le avec features.translateJson et une ou plusieurs entrées dans le json[] de niveau supérieur.
Substitutions de modèle par locale
translate-json résout les modèles par locale cible : d'abord localeModels(locale) lorsqu'il est configuré, puis translationModels. Utilisez cette option pour les bundles JSON imbriqués où certaines locales bénéficient de modèles dédiés — par exemple les fichiers de thème zh-Hans / zh-Hant. Consultez la page Modèles d'IA.
Étape 1 : Initialiser pour JSON imbriqué
ai-i18n-tools init -t ui-json-bundles -P ollamaCe modèle définit features.translateJson: true, désactive l'extraction de l'interface utilisateur et la traduction de documents, et génère un bloc json[] unique pointant vers src/i18n/en/translation.json avec la sortie src/i18n/{llocale}/translation.json. Il inclut également le bloc provider / providers pour le préréglage que vous passez avec -P — définissez la clé API correspondante (ou utilisez Ollama localement) avant d'exécuter translate-json ou sync ; consultez Fournisseur et clé API. Modifiez sourceLocale, targetLocales, contentPaths et outputPathTemplate pour la disposition de votre dépôt.
Étape 2 : Configurer json[]
Chaque bloc json[] décrit un pipeline :
contentPaths— un ou plusieurs fichiers.json, répertoires ou motifs génériques (par exemple"src/i18n/en/translation.json"ou"src/i18n/en/overrides/*.json"). Les chemins sont résolus à partir de la racine du projet.outputPathTemplate— obligatoire. Emplacement où écrire chaque fichier de langue cible. Variables disponibles :{locale},{LOCALE},{llocale}(code langue en minuscules, utile pour les dossiers de routes Astro),{stem},{basename},{extension},{relativeToSourceRoot}.targetLocales(facultatif) — sous-ensemble spécifique à ce bloc uniquement ; sinon, letargetLocalesracine s'applique.keyPolicy— indique quelles clés JSON contiennent du texte traduisible par rapport aux identifiants stables (voir ci-dessous).description(facultatif) — affiché dans les en-têtes CLI et dans la sortiestatus.
Exemple (plusieurs fichiers sources, dossiers de langue en minuscules) :
{
"sourceLocale": "en",
"targetLocales": ["de", "fr", "pt-BR"],
"features": {
"translateJson": true
},
"cacheDir": ".translation-cache",
"json": [
{
"description": "App UI bundle",
"contentPaths": [
"src/i18n/en/translation.json",
"src/i18n/en/overrides/*.json"
],
"outputPathTemplate": "src/i18n/{llocale}/{basename}",
"keyPolicy": {
"mode": "denylist",
"skipKeys": ["id", "slug", "href", "url", "key", "code"],
"translateKeys": []
}
}
]
}keyPolicy
mode | Comportement |
|---|---|
allowlist | Seules les clés correspondant à translateKeys (chemins avec points ; motifs minimatch) sont traduites. |
denylist | Traduit toutes les valeurs de type chaîne, sauf les clés correspondant à skipKeys. |
both | Applique d'abord translateKeys, puis retire les correspondances de skipKeys. |
Les chemins utilisent la notation par points (nav.home.label). Un nom simple comme slug correspond au segment final de la clé, à n'importe quelle profondeur.
Étape 3 : Traduire les bundles JSON
ai-i18n-tools translate-jsonIndicateurs facultatifs (mêmes idées que translate-docs) : -l / --locale pour un sous-ensemble de cibles, -p / --path pour limiter les fichiers, --dry-run, --force (effacer le suivi des fichiers et le cache de segments pour les fichiers correspondants), --force-update (retraiter lorsque le hachage du fichier correspond ; le cache de segments s’applique toujours), --check-cache (revalider les segments mis en cache pour les paramètres régionaux avec un script natif appliqué même lorsque le suivi des fichiers correspond), -b / --batch-concurrency, --prompt-format (xml | json-array | json-object).
Les projets uniquement JSON peuvent exécuter :
ai-i18n-tools sync --no-ui --no-svg --no-docsLorsque l'interface ou la documentation sont également activées, sync exécute translate-json après translate-docs (sauf si --no-json). Ignorez la traduction JSON avec --no-json.
Vérifiez la couverture par fichier et par langue :
ai-i18n-tools statusLorsque translateJson est activé, status affiche une section json[] (✓ à jour, ● périmée ou manquante).
JSON vs autres pipelines
| Situation | Utilisation |
|---|---|
Chaînes d'interface utilisateur dans t("…") / i18n.t("…") en JS/TS/Astro | Chaînes d'interface utilisateur — extract + translate-ui |
Catalogue Docusaurus write-translations ({ "key": { "message": "…", "description": "…" } }) | Documents — docs[].docusaurusCatalogDir + translate-docs, pas json[] |
| Chaînes de thème/nav/barre latérale VitePress | Documents — docsOutput.vitepressThemeCatalog + translate-docs; n'utilisez pas json[] — voir Intégration VitePress |
Étiquettes Nextra _meta.ts et dictionnaire de thème .ts | Documents — translate-docs (auto _meta lorsque style: "nextra", facultatif nextraDictionaryPath); n'utilisez pas json[] — voir Intégration Nextra |
Étiquettes Fumadocs meta.json et catalogue de substitutions d'interface | Documents — translate-docs (auto meta.json lorsque style: "fumadocs", facultatif fumadocsUiCatalog); n'utilisez pas json[] — voir Intégration Fumadocs |
JSON de locale imbriquée autonome (arborescences translation.json de style ZenBrowser) | JSON — json[] + translate-json |
Fichiers d'espace de noms i18next (jetons public/locales/en/common.json, {{name}}, suffixes key_one / key_other) | JSON — json[] + translate-json (voir fichiers d'espace de noms i18next) |
Dictionnaires Intlayer *.content.ts + useIntlayer (quitter Intlayer) | Migration depuis Intlayer — migrate-intlayer, puis les chaînes d'interface utilisateur |
Dictionnaires Intlayer *.content.ts (conserver Intlayer, remplir les traductions) | Traduire Intlayer sur place — translate-intlayer |
Fichiers .svg illustrés avec <text> / <title> / <desc> | features.translateSVG + svg + translate-svg (facultatif ; pas l'un des trois pipelines principaux) |
Référence de champ : json dans Référence de configuration. Les clés de cache pour le nettoyage utilisent json-block:{blockIndex}:{projectRelPath} dans file_tracking.
Fichiers d'espace de noms i18next
Le pipeline JSON couvre les fichiers de locale clé/valeur i18next typiques : objets imbriqués, tableaux de chaînes, interpolation {{name}} dans les valeurs, et clés de suffixe pluriel indépendantes (welcome_one, welcome_other). Il ne réécrit pas les sites d'appel t("some.key") — ceux-ci restent basés sur des clés. Pour faire passer un projet au schéma t() de chaînes source de ai-i18n-tools, modifiez les sites d'appel en t("source text"). Le texte est écrit en sourceLocale, qui peut être n'importe quelle langue. Lorsque la source est Intlayer .content.ts, exécutez migrate-intlayer. Pour conserver Intlayer et ne traduire que ses dictionnaires, utilisez translate-intlayer.
Exemple (espaces de noms sources anglais sous public/locales/en/) :
{
"sourceLocale": "en",
"targetLocales": ["de", "fr", "pt-BR"],
"features": { "translateJson": true },
"json": [
{
"description": "i18next namespaces",
"contentPaths": ["public/locales/en/*.json"],
"outputPathTemplate": "public/locales/{locale}/{basename}"
}
]
}key_one / key_other / key_zero (et autres suffixes CLDR) sont traduits comme des feuilles distinctes. Cela suffit à i18next pour continuer à résoudre les pluriels par suffixe ; le pipeline ne les regroupe pas en une seule ligne de catalogue.