ai-i18n-tools

Appearance

JSON ​

Conçu pour les projets qui conservent le texte de l'interface utilisateur dans des fichiers JSON imbriqués par paramètres régionaux (par exemple src/i18n/en/translation.json) au lieu de t("…") dans le code source. L'interface de ligne de commande parcourt les valeurs de chaîne dans ces fichiers, les traduit via le fournisseur LLM actif et écrit les sorties par paramètres régionaux à l'aide de json[].outputPathTemplate. Elle 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 : localeModels(locale) en premier lorsqu'il est configuré, puis translationModels. Utilisez ceci 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. Voir Fournisseurs et modèles.

Étape 1 : Initialiser pour JSON imbriqué ​

bash
ai-i18n-tools init -t ui-json-bundles [-P <provider>]

Ce modèle définit features.translateJson: true, désactive l'extraction de l'interface utilisateur et la traduction de documents, et échafaude un seul bloc json[] pointant vers src/i18n/en/translation.json avec la sortie src/i18n/{llocale}/translation.json. Il inclut également un bloc provider / providers par défaut (openrouter sauf si vous passez -P <provider>) — définissez la clé API correspondante (ou utilisez Ollama local) avant d'exécuter translate-json ou sync ; voir 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 + useIntlayerMigration depuis Intlayer — migrate-intlayer, puis chaînes d'interface utilisateur
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 paramètres régionaux 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 sources anglaises de ai-i18n-tools, modifiez les sites d'appel en t("English text") (ou exécutez migrate-intlayer lorsque la source est Intlayer .content.ts).

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.

Copyright © Waldemar Scudeller Jr.