Skip to content

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é ​

bash
ai-i18n-tools init -t ui-json-bundles -P ollama

Ce 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, le targetLocales racine 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 sortie status.

Exemple (plusieurs fichiers sources, dossiers de langue en minuscules) :

json
{
  "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

modeComportement
allowlistSeules les clés correspondant à translateKeys (chemins avec points ; motifs minimatch) sont traduites.
denylistTraduit toutes les valeurs de type chaîne, sauf les clés correspondant à skipKeys.
bothApplique 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 ​

bash
ai-i18n-tools translate-json

Indicateurs 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 :

bash
ai-i18n-tools sync --no-ui --no-svg --no-docs

Lorsque 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 :

bash
ai-i18n-tools status

Lorsque translateJson est activé, status affiche une section json[] (✓ à jour, ● périmée ou manquante).

JSON vs autres pipelines ​

SituationUtilisation
Chaînes d'interface utilisateur dans t("…") / i18n.t("…") en JS/TS/AstroChaî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 VitePressDocuments — docsOutput.vitepressThemeCatalog + translate-docs; n'utilisez pas json[] — voir Intégration VitePress
Étiquettes Nextra _meta.ts et dictionnaire de thème .tsDocuments — 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'interfaceDocuments — 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/) :

json
{
  "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.

Publié sous licence MIT.