Skip to content

Architecture ​

Aperçu de l'architecture ​

Le code est organisé en quatre couches. Utilisez cette section pour le modèle mental ; ouvrez l'arborescence des sources lorsque vous avez besoin de détails au niveau du fichier.

Comment une exécution sync s'articule ​

sync (et les commandes de traduction individuelles) exécutent les fonctionnalités activées dans l'ordre :

ÉtapeCommandeCe qu'elle fait
1extract → translate-uiAnalyser les sources de l'interface utilisateur → mettre à jour strings.json → remplir le JSON de locale plat (de.json, …)
2translate-svg (facultatif)Traduire le texte SVG sous config.svg
3translate-docsTraduire les pages Markdown, MDX, .astro ; le JSON du catalogue Docusaurus ; le dictionnaire _meta / .ts de Nextra ; le catalogue de thèmes VitePress
4translate-json (facultatif)Traduire les feuilles JSON imbriquées sous json[]

Chaque pipeline suit la même boucle principale : extraire les segments → protéger la syntaxe → regrouper → rechercher dans le cache ou appeler le LLM → écrire la sortie. Les services partagés au milieu — configuration, espaces réservés, cache, glossaire, LlmClient — sont décrits sous Infrastructure partagée.

Carte des modules ​

CoucheDossierRôle
Entréesrc/cli/Commandes CLI : init, extract, mark-html, translate-ui, translate-docs, translate-json, translate-svg, sync, status, dashboard, …
Pipelinessrc/extractors/Extraction de segments à partir de JS/TS, marqueurs HTML, markdown, JSON, SVG, .astro
src/processors/Protection des espaces réservés, regroupement, validation, réécriture de liens
Partagésrc/core/Configuration, types, cache SQLite, invites, chemins de sortie, utilitaires de locale
src/api/LlmClient — client de chat agnostique du fournisseur (Vercel AI SDK) avec repli de modèle
src/glossary/Chargement du glossaire, suggestions de termes et fichiers de contexte de projet facultatifs pour les invites
src/utils/Logger, hachage, analyseur d'ignorance, tables de largeur d'affichage, chargeur .env
Runtime de votre applicationsrc/runtime/Assistants i18next et utilitaires d'affichage — exportés sous le nom de 'ai-i18n-tools/runtime' (Assistants d'exécution)
Interface de l'outil (dogfooding)src/i18n/, src/dashboard-app/, src/server/Localise la CLI et le tableau de bord de traduction de ce package — séparément du contenu de votre projet (Auto-localisation)

Tout ce qui est destiné à un usage programmatique est réexporté depuis src/index.ts (API programmatique).

Résumés des pipelines ​

PipelineSectionEntrée → sortie
Chaînes d'interface utilisateurInternes des chaînes d'interface utilisateurFichiers source → strings.json → {locale}.json plat
DocumentsInternes des documentsMarkdown / MDX / .astro / Docusaurus JSON → fichiers par locale sous docs[].outputDir
Bundles JSONInternes JSONJSON imbriqué sous json[] → fichiers JSON par locale
SVGInternes des documents — extracteursFichiers SVG sous config.svg → copies SVG traduites

Internes des chaînes d’interface utilisateur ​

ÉtapeComposantRésultat
1Fichiers source (JS/TS ; .astro / .html facultatifs)Fichiers sur disque
2UIStringExtractor (Babel via ui-string-babel.ts)Segments identifiés par hachage MD5
3strings.jsonCatalogue maître : { hash: { source, translated, models?, locations? } }
4LlmClient.translateUIBatch()Tableau JSON de chaînes source → traductions (+ ID de modèle par lot)
5de.json, pt-BR.json, …Mappages plats : chaîne source → traduction (pas de métadonnées de modèle)

UIStringExtractor ​

extractUiCallsFromFileContent dans ui-string-babel.ts trouve les appels t("literal") et i18n.t("literal"). Les fichiers JS et TS sont analysés avec @babel/parser (source de module, TypeScript et JSX). Pour les sources .astro (lorsqu'elles sont listées dans ui.uiExtractor.extensions), la même fonction analyse le frontmatter et les blocs de modèle {expression} et applique les mêmes règles funcNames. Les noms de fonction et les extensions de fichier sont configurables via ui.uiExtractor (ui.reactExtractor est un alias pris en charge). extract fusionne également des entrées supplémentaires dans le même catalogue : le package.json description du projet lorsque includePackageDescription est activé (par défaut), et chaque englishName du catalogue maître ui-languages fourni (construit à partir de sourceLocale + targetLocales) lorsque includeUiLanguageEnglishNames est true (les chaînes déjà trouvées dans la source conservent la priorité ; ne lit pas languagesManifestPath). extract régénère également ui-languages.json à languagesManifestPath. Les hachages de segment sont les 8 premiers caractères hexadécimaux MD5 de la chaîne source tronquée — ceux-ci deviennent les clés dans strings.json.

Pour les sources .html / .htm (lorsqu'elles sont listées dans ui.uiExtractor.extensions), extract achemine plutôt le fichier via html-i18n-marks.ts, qui analyse les attributs de marqueur data-i18n / data-i18n-title / data-i18n-placeholder / data-i18n-alt / data-i18n-aria-label (configurables via ui.uiExtractor.htmlI18nAttributes). Un marqueur nu prend son texte source de la propre textContent ou de l'attribut de l'élément ; un marqueur valorisé (data-i18n="Key") utilise la valeur. data-i18n-locale-src et data-i18n-locale-href sont réservés à l'environnement d'exécution du navigateur et ne sont jamais extraits. Le même module alimente la commande mark-html, qui insère automatiquement les marqueurs nus (y compris alt et aria-label) et n'insère jamais les marqueurs d'URL de locale. Les fichiers HTML n'atteignent jamais la passe Babel. Le HTML de locale généré sous un outputDir de documentation est exclu de cette analyse.

Les sites SSG Astro simples peuvent ignorer i18next : charger des {locale}.json plats à la compilation et résoudre les t('source text') par clé de texte source. La langue source est sourceLocale et peut être n'importe quelle langue (voir examples/astro-website/src/i18n/t.ts et Chaînes d'IU — site web Astro).

Les applications HTML simples suivent le même modèle de catalogue avec des attributs de marqueur au lieu d'appels t() — voir Marquage HTML pour la traduction. Le script prêt à l'emploi est ai-i18n-tools/html-runtime/i18n.js.

Le HTML statique qui doit devenir un fichier par locale suit un pipeline de documents (HtmlTemplateExtractor dans translate-docs), et non ce catalogue. Voir Pages HTML.

strings.json ​

Le catalogue principal a la forme suivante :

json
{
  "a1b2c3d4": {
    "source": "The English string",
    "translated": {
      "de": "Der deutsche Text",
      "pt-BR": "O texto em português"
    },
    "models": {
      "de": "anthropic/claude-3.5-haiku",
      "pt-BR": "openai/gpt-4o"
    },
    "locations": [{ "file": "src/app/page.tsx", "line": 51 }]
  }
}

models (facultatif) — par locale, quel modèle a produit cette traduction après la dernière exécution réussie de translate-ui pour cette locale (ou user-edited si le texte a été enregistré depuis le tableau de bord de traduction). locations (facultatif) — où extract a trouvé la chaîne (scanner + ligne de description du package ; les chaînes englishName du maître fourni peuvent omettre locations).

extract ajoute de nouvelles clés et préserve les données translated / models existantes pour les clés toujours présentes dans l'analyse (littéraux du scanner, description facultative, englishName du maître fourni facultatif). translate-ui remplit les entrées translated manquantes, met à jour models pour les locales qu'il traduit, et écrit les fichiers de locale plats.

ui-languages.json manifeste — tableau JSON de { code, label, englishName, direction } (BCP-47 code, UI label, référence englishName, "ltr" ou "rtl"). Utilisez generate-ui-languages ou extract pour construire un fichier de projet à partir de sourceLocale + targetLocales et du data/ui-languages-complete.json maître fourni.

Fichiers de locale plats ​

Chaque langue cible obtient un fichier JSON plat (de.json) qui associe chaîne source → traduction (sans champ models) :

json
{
  "The English string": "Der deutsche Text",
  "Save": "Speichern"
}

i18next charge ces fichiers comme des bundles de ressources et recherche les traductions à partir de la chaîne source (modèle clé-par-défaut).

Messages de traduction pour l'interface ​

buildUIPromptMessages construit des messages système et utilisateur qui :

  • Identifier les langues source et cible (par le nom d'affichage de localeDisplayNames ou ui-languages.json).
  • Préfixer une directive de script lorsque la locale cible a un système d'écriture attendu (script BCP-47 explicite, ou une langue par défaut telle que hi → Devanagari, ar → Arabe, ja → Kana/Kanji japonais).
  • Envoyer un tableau JSON de chaînes et demander un tableau JSON de traductions en retour.
  • Inclure des indications de glossaire si disponibles.

LlmClient.translateUIBatch essaie chaque modèle dans l'ordre, en se rabattant sur les erreurs d'analyse, de réseau ou de script incorrect (y compris le repli romanisé/latin pour les locales à script natif). La CLI construit cette liste par locale cible à partir de localeModels, de uiModels facultatif et de translationModels (voir Modèles d'IA).


Internes des documents ​

ÉtapeComposantRésultat
1Fichiers Markdown / MDX / JSON / .astro (translate-docs)Fichiers source
2MarkdownExtractor / JsonExtractor / AstroTemplateExtractorsegments[] — segments typés avec hachage + contenu
3PlaceholderHandlerTexte protégé — HTML, avertissements, ancres, MDX, URL, code en ligne, emphase masquée en tant que jetons
4splitTranslatableIntoBatchesbatches[] — regroupés par nombre + limite de caractères
5Recherche TranslationCacheCache hit → ignorer ; miss → LlmClient.translateDocumentBatch
6PlaceholderHandler.restoreAfterTranslationTexte final — espaces réservés restaurés
7resolveDocumentationOutputPathFichier de sortie — mise en page Docusaurus ou mise en page plate

Extracteurs ​

Tous les extracteurs étendent BaseExtractor et implémentent extract(content, filepath): Segment[].

  • MarkdownExtractor – divise le Markdown en segments typés : frontmatter, heading, paragraph, code, admonition. Le frontmatter YAML est classé comme non traduisible (slug, id et les autres clés de routage restent stables). Les blocs export ... de niveau supérieur (par exemple, les définitions de composants React) sont classés comme segments other non traduisibles, parallèlement à la gestion import ... existante. Les blocs multilignes commençant par une balise JSX en majuscules (par exemple, un bloc <Tabs>) sont classés comme paragraphes traduisibles. Les segments non traduisibles (blocs de code, HTML brut) sont conservés tels quels.
  • AstroTemplateExtractor – analyse et remplacement pour les pages marketing .astro (translate-docs via translateAstroFile dans doc-translate.ts). Extrait les nœuds de texte HTML visibles par l'utilisateur et les attributs traduisibles (alt, title, aria-label, placeholder), ainsi que les littéraux de chaîne à l'intérieur des blocs de modèle {expression} lorsqu'ils sont visibles par l'utilisateur. Ignore le TypeScript du frontmatter, <script>, <style>, les valeurs d'attribut/clé protégées et les littéraux à l'intérieur de t('…'). Le réassemblage ajuste les importations relatives lorsque les chemins de sortie sont plus profonds (par exemple, src/pages/de/index.astro). Voir Pages du site web Astro.
  • JsonExtractor – extrait les valeurs de chaîne des fichiers d'étiquettes JSON de Docusaurus (catalogues d'IU Docusaurus, pas le corps MDX).
  • SvgExtractor – extrait le contenu <text>, <title> et <desc> du SVG (utilisé par translate-svg pour les fichiers sous config.svg, pas par translate-docs).
  • html-i18n-marks.ts - un analyseur de balises HTML ciblé utilisé par extract pour les sources .html / .htm et par la commande mark-html. collectHtmlI18nStrings / collectHtmlI18nLocations lisent les attributs de marqueur data-i18n* (marqueur nu → textContent / title / placeholder de l'élément ; marqueur valorisé → la valeur), et markHtmlContent insère les marqueurs nus dans les éléments de texte feuille / titre / placeholder (idempotent, respecte data-i18n-ignore, ignore les éléments de type code et à contenu mixte). L'utilitaire partagé normalizeI18nText maintient les clés de build identiques à celles du runtime du navigateur.

Sites hybrides Astro (IU + HTML des pages) ​

Les applications Astro simples activent souvent à la fois les chaînes d’interface utilisateur et les documents dans une seule configuration (référence : examples/astro-website/) :

CoucheMécanismeSortie
HTML de modèleAstroTemplateExtractor + translate-docs.astro par locale sous docs[].outputDir
Frontmatter / t('…')ui-string-babel.ts + extract + translate-uipublic/locales/{locale}.json plat (chaîne de langue source comme clé ; sourceLocale peut être n'importe quelle langue)

La commande sync exécute les étapes activées dans l’ordre : extraction puis traduction de l’interface utilisateur (lorsque features.translateUIStrings) → traduction SVG facultative → traduction des documents → traduction JSON facultative (sauf si ignorée avec --no-ui, --no-svg, --no-docs ou --no-json). Le modèle d’initialisation ui-astro-website ne génère que les chaînes d’interface utilisateur ; ajoutez docs[] et features.translateDocs pour le HTML de la page.

Insertion d'ancre de titre (write-heading-ids CLI) ​

La commande write-heading-ids est un préprocesseur local et non basé sur un LLM pour les fichiers Markdown de documentation. Implémentation : src/cli/write-heading-ids.ts orchestre la découverte des fichiers ; src/markdown/write-heading-ids-core.ts analyse les lignes et insère les ancres.

Il nécessite une configuration valide avec au moins un bloc docs[]. Pour chaque bloc, il rassemble les fichiers .md / .mdx sous contentPaths, applique les règles .translate-ignore du projet (même idée que la traduction de documentation), et se restreint éventuellement à une sous-arborescence avec --path / --file. Chaque fichier est transformé avec applyHeadingAnchorsToMarkdown : pour chaque titre ATX plat (# … à ###### …) en dehors des blocs de code clôturés, les identifiants de titre existants de toute forme sont remplacés par le style sélectionné. Les styles HTML écrivent <a id="slug"></a> sur la ligne au-dessus d'un titre sans suffixe ; --slug-style mdx-comment écrit {/* #slug */} sur la ligne du titre (et supprime une ancre HTML précédente). Les slugs proviennent toujours du texte du titre actuel. --remove supprime les ancres HTML, les suffixes classiques {#id} et les identifiants de commentaire MDX sans en écrire de nouveaux. Les algorithmes de slug correspondent aux écosystèmes courants — github (par défaut), bitbucket, gitlab, pymdown (normalisation Unicode facultative / drapeaux d'encodage en pourcentage), azure-devops, plus mdx-comment (slug github + sortie de commentaire MDX) — afin que les identifiants d'ancre restent cohérents avec les outils existants (doctoc, PyMdown, Docusaurus, etc.). --dry-run signale les modifications potentielles sans les écrire.

Après le passage source, la même commande repositionne ces identifiants anglais sur le markdown traduit existant de chaque locale (resolveTranslatedOutputPath). Les titres traduits ne sont jamais re-slugifiés ; un {#id} / {/* #id */} en milieu de titre est replacé à la fin (ou ancre HTML) que le style sélectionné attend. Les fichiers de locale manquants sont ignorés.

Cette commande ne s'exécute pas dans translate-docs ou sync ; exécutez-la explicitement lorsque vous souhaitez des identifiants de fragment stables dans les fichiers sources avant traduction ou publication.

Protection des espaces réservés ​

Avant la traduction, la syntaxe sensible est remplacée par des jetons opaques afin d'éviter toute corruption par le LLM, appliquée dans cet ordre (la restauration s'effectue dans l'ordre inverse) :

  1. Blocs de code délimités (trois backticks ou tildes ou plus, y compris un délimiteur plus long qui en enveloppe un plus court) : le délimiteur entier, y compris la chaîne d'information, est remplacé par {{CDF_N}} et conservé dans l'ordre avec les autres jetons structurels. Cela maintient en place les exemples à l'intérieur de conteneurs tels que ::: code-group ou ::: tip. Les chaînes d'information des délimiteurs (étiquettes d'onglet VitePress) restent dans la langue source. Un délimiteur d'ouverture non fermé est laissé sous forme de texte afin qu'un délimiteur de fermeture ultérieur ne soit pas absorbé.
  2. Suffixes d'ID de titre ({#id} classique / {/* #id */} MDX à la fin d'un titre ATX) : entièrement retirés de la ligne et non envoyés au modèle. Après restauration, ils sont réépinglés à la fin du titre correspondant afin que Docusaurus voie toujours un ID valide. Les commentaires en milieu de titre restent dans le texte et sont gérés par les couches MDX / {#…} ultérieures. Les titres à l'intérieur d'un délimiteur masqué ne sont pas retirés.
  3. Balises et commentaires HTML (<strong>, <!-- ... -->, etc.) : les balises HTML en minuscules provenant d'une liste d'autorisation connue sont remplacées par des jetons {{HTM_N}}. Les balises JSX en majuscules (<Highlight>, <Tabs>, </Tab>) sont gérées séparément par la couche MDX (étape 6).
  4. Marqueurs d'avertissement (:::note, :::) : seul le préfixe de la directive sur la ligne d'ouverture est remplacé par {{ADM_OPEN_N}} ; tout titre sur la même ligne est laissé au modèle pour traduction. Restauré avec le texte original exact.
  5. Ancres de document (HTML <a id="…">, restes de {#…} Docusaurus en milieu de titre) : conservées telles quelles.
  6. Constructions MDX uniquement (src/processors/mdx-placeholders.ts) :
    • Commentaires MDX ({/* … */}, y compris un {/* #my-id */} en milieu de titre qui n'était pas un suffixe de fin de ligne) : remplacés par {{MDX_N}}.
    • Balises JSX en majuscules (<Highlight>, <Tabs>, <TabItem>, <TOCInline />, </Highlight>) : conservées sous la forme {{MDX_N}} avec les attributs de chaîne traduisibles (label, tooltip, aria-label) réécrits en {{JXA_N}} à l'intérieur de la balise, sauf si le nom de l'attribut apparaît dans docs[].protectAttributes ; label: à l'intérieur des littéraux d'objet <Tabs values={[ { label: '…' } ]}> (pouvant être ignoré via docs[].protectKeys) et <TabItem value="…"> (lorsqu'aucun attribut label n'existe, en ignorant les valeurs de type slug en minuscules) sont également extraits. Ajoutés au segment sous forme de lignes ||JXA_N: …||, puis réintégrés par restoreMdx.
    • Expressions MDX entre accolades ({frontMatter.title}, style={{…}}) : correspondance sensible à la profondeur, remplacées par {{MDX_N}}.
  7. URL Markdown (](url), src="…") : restaurées à partir d'une carte après la traduction.
  8. Fragments de code en ligne (`code`) et code en ligne entouré de gras (**code**) : conservés.
  9. Mise en évidence Markdown (facultatif, activé automatiquement pour les locales CJK/RTL) : délimiteurs de mise en évidence masqués.

Une fois que le modèle a renvoyé sa réponse, translate-docs restaure les cartes et valide le segment : le même multiensemble de jetons entre doubles accolades doit être présent, les jetons structurels ({{HTM_N}}, les marqueurs d'avertissement, {{CDF_N}}) doivent conserver leur sous-séquence ordonnée (les jetons de contenu tels que {{ILC_N}} / {{URL_N}} / {{SE}} peuvent se déplacer avec l'ordre des mots), les types de balises HTML restaurées doivent correspondre à la source non protégée, et tout identifiant entre doubles accolades restant doit déjà avoir existé dans la source (les jetons inventés provoquent donc un échec). L'invite de document demande également aux modèles de copier chaque jeton une seule fois, de conserver l'ordre des jetons structurels et de ne pas inventer de nouveaux délimiteurs à doubles accolades ; les vérifications mécaniques font autorité.

La protection partagée des attributs/clés pour les modèles Astro et MDX JSX est implémentée dans src/processors/expression-attribute-protection.ts et pilotée par bloc par docs[].protectAttributes et docs[].protectKeys (voir protectAttributes / protectKeys).

Cache (TranslationCache) ​

Une base de données SQLite (via node:sqlite) stocke des lignes indexées par (source_hash, locale), avec translated_text, model, filepath, last_hit_at et des champs associés. Le hachage correspond aux 16 premiers caractères hexadécimaux SHA-256 du contenu normalisé (espaces réduits).

À chaque exécution, les segments sont recherchés par hachage × locale. Seules les absences de cache sont envoyées au LLM. Après la traduction, last_hit_at est réinitialisé pour les lignes de segment dans la portée de traduction actuelle qui n'ont pas été atteintes. Les succès de cache lors de la traduction de documents effacent les lignes translation_failures obsolètes pour ce segment.

cleanup exécute sync --force-update en premier, puis :

  • supprime les lignes de segment obsolètes (last_hit_at nul / chemin de fichier vide) ;
  • élague les clés file_tracking lorsque le chemin source résolu est manquant sur le disque (doc-block:…, json-block:…, svg-files:…, etc.) ;
  • supprime les lignes de traduction dont le chemin de fichier de métadonnées pointe vers un fichier manquant ;
  • élague les lignes translation_failures orphelines ;
  • élague les lignes markdown_source_issues orphelines dont le chemin source résolu est manquant sur le disque ;
  • supprime les lignes de cache pour les locales absentes de la configuration (sourceLocale, targetLocales racine, et tout docs[] / json[] targetLocales par bloc ; SQLite uniquement — utilisez purge-locale pour supprimer les fichiers générés).

Il ne sauvegarde pas cache.db à moins que --backup <path> ne soit passé, ce qui écrit d'abord une sauvegarde à ce chemin.

Les appels au modèle facturés (traductions acceptées et tentatives ignorées) sont stockés dans api_calls. Après une commande ayant enregistré des appels, les lignes de détail datant de plus de sept jours calendaires UTC sont transférées vers les api_totals. usage et la vue Utilisation et coûts du tableau de bord combinent ces deux tables. Voir Utilisation et coûts.

Les notes de glossaire Context et les glossary.contextFiles sont empreintées (prompt_context_hash) et injectées dans l'interface utilisateur, la documentation, les fichiers JSON, SVG et les invites de relecture. La modification de ces directives invalide les segments mis en cache correspondants et les lignes de suivi de fichiers lors de la prochaine exécution. Les lignes de cache du tableau de bord user-edited sont conservées. La modification d'une seule traduction de glossaire préférée sur une ligne non forcée laisse le cache existant en place jusqu'à --force / --force-update. Une ligne Force manque le cache uniquement pour les segments dont la source contient ce terme lorsque le texte stocké n'inclut pas déjà la traduction forcée, et le saut de fichier inchangé est refusé pour un fichier dont la sortie le manque toujours. Laissez Context vide sur cette ligne ; une note de contexte rafraîchit toujours l'ensemble de la locale. Markdown rejette également un segment traduit qui omet une étiquette d'interface utilisateur citée de deux à cinq mots (clé de catalogue ou préfixe amorcé en forme d'étiquette). Une citation est en gras, du code en ligne, un titre ou une ligne qui n'est que cette étiquette. La casse de titre à l'intérieur d'une phrase est une indication, afin que la traduction puisse s'infléchir (le hindi Cursor account peut devenir कर्सर खाते plutôt que la forme de dictionnaire कर्सर खाता). Une étiquette d'un seul mot de contenu telle que Sign in reste une indication. La vérification ignore la capitalisation dans la traduction, donc une étiquette en minuscules dans la phrase compte toujours lorsque la source la cite. La prose ordinaire qui utilise les mêmes mots peut les infléchir. Un préfixe amorcé doit être une étiquette capitalisée dont la traduction partagée est une courte phrase sans espace réservé ; les débuts de phrase ne sont pas amorcés. Cette vérification relance le modèle suivant et ne divise pas le segment.

La commande translate-docs utilise également le suivi des fichiers afin que les sources inchangées avec des sorties existantes et à jour puissent ignorer complètement le travail. --check-cache rouvre les locales avec un système d'écriture attendu afin que les segments mis en cache soient revalidés ; --force-update réexécute le traitement des fichiers pour chaque locale tout en utilisant le cache de segments ; --force efface le suivi des fichiers et contourne les lectures du cache de segments pour la traduction API. Lorsque les modèles essayés pour un segment Markdown échouent la validation AST, translate-docs peut fractionner progressivement le segment et réessayer des parties plus petites (docs[].segmentSplitting.qualityRetrySplit, activé par défaut). Trois fois la même erreur de qualité met fin prématurément à cette liste de modèles. Voir Documents — comportement du cache et indicateurs pour le tableau complet des indicateurs.

Format d'invite de lot : translate-docs --prompt-format sélectionne les formes XML (<seg> / <t>) ou tableau/objet JSON pour LlmClient.translateDocumentBatch uniquement ; l'extraction, les espaces réservés et la validation restent inchangés. Voir Format d'invite de lot.

Résolution du chemin de sortie ​

resolveDocumentationOutputPath(config, cwd, locale, relPath, kind) associe un chemin relatif à la source au chemin de sortie :

  • Style nested (par défaut) : {outputDir}/{locale}/{relPath} pour le markdown.
  • Style doc-system : sous docsRoot, les sorties utilisent {outputDir}/{locale}/[localeSubpath/]{relativeToDocsRoot} ; les chemins en dehors de docsRoot reviennent à la disposition imbriquée. Alias : docusaurus (par défaut localeSubpath = chemin du plugin Docusaurus), astro-starlight (par défaut vide localeSubpath), vitepress (identique à doc-system avec localeSubpath vide ; préserve la casse des dossiers BCP-47).
  • Style flat : {outputDir}/{stem}.{locale}{extension}. Lorsque flatPreserveRelativeDir est true, les sous-répertoires source sont conservés sous outputDir.
  • Personnalisé pathTemplate : toute disposition markdown utilisant {outputDir}, {locale}, {LOCALE}, {relPath}, {stem}, {basename}, {extension}, {docsRoot}, {relativeToDocsRoot}.
  • Personnalisé jsonPathTemplate : disposition personnalisée séparée pour les fichiers d'étiquettes JSON, utilisant les mêmes espaces réservés.
  • linkRewriteDocsRoot aide le réécriture de liens plats à calculer les préfixes corrects lorsque la sortie traduite est située ailleurs que dans le répertoire racine par défaut du projet.

Réécriture des liens plats ​

Lorsque docsOutput.style === "flat", les fichiers markdown traduits sont placés à côté de la source avec des suffixes de paramètres régionaux. Les liens relatifs entre les pages sont réécrits de sorte que [Guide](./guide.md) dans readme.de.md pointe vers guide.de.md. Contrôlé par rewriteRelativeLinks (activé automatiquement pour le style plat sans pathTemplate personnalisé). Le même passage ajoute un préfixe de profondeur par fichier aux URL d’actifs non-markdown avant l’exécution de postProcessing.regexAdjustments — voir Réécriture de liens plats.


Internes JSON ​

ÉtapeComposantRésultat
1json[].contentPathsFichiers résolus (fichier, répertoire ou glob)
2NestedJsonExtractorFeuilles de chaîne sélectionnées par keyPolicy (chemins de points + minimatch)
3PlaceholderHandler + lot + TranslationCacheCache hit → ignorer ; miss → LlmClient.translateDocumentBatch (SQLite partagé)
4NestedJsonExtractor.reassembleFichier de sortie via expandJsonBlockOutputPath(outputPathTemplate)
  • NestedJsonExtractor (src/extractors/nested-json-extractor.ts) parcourt un JSON imbriqué arbitraire et émet un segment par feuille de chaîne traduisible. keyPolicy.mode (allowlist, denylist ou both) filtre les chemins avec minimatch sur la notation par points (les noms simples comme slug correspondent au segment de clé final).
  • Le suivi des fichiers de cache utilise json-block:{blockIndex}:{projectRelPath} dans file_tracking (même cacheDir que les documents et SVG).
  • Pas pour les catalogues write-translations de Docusaurus (forme { message, description }) — ceux-ci utilisent les documents (docs[].docusaurusCatalogDir + JsonExtractor à l’intérieur de translate-docs).
  • Pas pour les chaînes d’interface utilisateur t() — chaînes d’interface utilisateur (strings.json + paquets plats).
  • CLI : translate-json ; orchestration dans src/cli/translate-json-run.ts. Modèle d'initialisation : ui-json-bundles.

Infrastructure partagée ​

LlmClient ​

Client de chat indépendant du fournisseur, basé sur le Vercel AI SDK (ai + @ai-sdk/openai-compatible). Il résout le fournisseur actif à partir de provider / providers, construit un client compatible OpenAI (createOpenAICompatible) pour la baseUrl et la clé API de ce fournisseur, et achemine tous les appels via generateText. OpenRouterClient est conservé comme alias obsolète. Comportements clés :

  • Repli de modèle : essaie chaque modèle de la liste résolue dans l'ordre ; se replie en cas d'échec de requête ou d'analyse. Chaque locale cible obtient sa propre chaîne résolue : localeModels(locale) en premier lorsqu'il est configuré, puis uiModels (pipelines d'interface utilisateur uniquement), puis translationModels. La traduction de documents, JSON et SVG crée un client par locale avec la chaîne non-UI. La commande bench-models construit plutôt un client à modèle unique par ID configuré (union de translationModels, uiModels et localeModels ; translationModels: [id], sans repli) afin de pouvoir chronométrer et tarifer chaque modèle indépendamment.
  • Délai d'expiration de la requête : requestTimeout (secondes) ou requestTimeoutMs sur le fournisseur actif, sinon les mêmes clés en haut de la configuration (par défaut 120 secondes), interrompt chaque requête via AbortSignal.timeout. La même valeur s'applique à GET /models lorsque la CLI charge la liste des modèles d'un fournisseur pour check-models (tout fournisseur). Le filtre de pré-vol optionnel qui supprime les ID de modèle inconnus ne s'exécute que lorsque le fournisseur actif est OpenRouter.
  • Fonctionnalités supplémentaires d'OpenRouter (uniquement lorsque openrouter est actif) : routage du débit via le champ de requête provider et les en-têtes HTTP-Referer / X-Title. L'utilisation des jetons est signalée pour chaque fournisseur. OpenRouter et Cheaper Inference renvoient également un montant facturé en USD (usage.cost ; Cheaper Inference se replie sur cheaper_inference.billing.billed_cost_usd). Lorsque le fournisseur omet ce montant, le coût en USD est calculé à partir de providers.<name>.modelPricing, puis de la valeur par défaut pricing à l'échelle du fournisseur, puis du prix catalogue d'entrée et de sortie de models.dev, et stocké sur la ligne api_calls. Un coût signalé par le fournisseur (y compris 0) n'est jamais remplacé. Le coût inconnu reste non défini. La tarification d'un appel ne lit que la tranche models.dev de <cacheDir>/benchmark-scores.json ; elle ne télécharge pas languagebench ni le fichier Arena.
  • Journal de trafic de débogage : si debugTrafficFilePath est défini, ajoute le JSON de la requête et de la réponse à un fichier (programmatique). La CLI --debug-failed écrit des fichiers FAILED-TRANSLATION sous cacheDir avec l'invite système/utilisateur, la réponse brute de l'assistant et les erreurs de validation pour les tentatives échouées de vérification de traduction d'interface utilisateur, de documents, JSON et SVG. Les échecs d'API de fournisseur / de corps vide s'affichent sur la console au lieu de vider un fichier contenant uniquement l'invite.

suggest-models et l'onglet Modèles du tableau de bord n'appellent pas le LLM. Ils classent le catalogue de chat du fournisseur actif avec un indice de qualité basé sur le ChrF de languagebench et le Arena Score de LMArena. Le prix est un taux mixte 3:1 en USD par million de tokens (catalogue, puis models.dev, puis languagebench). --quality trie par indice ; --price parcourt la frontière de Pareto qualité-prix. Ils remplacent éventuellement providers.<name>.translationModels. Les agrégats se trouvent dans <cacheDir>/benchmark-scores.json. Voir Modèles IA et suggest-models.

Chargement de la configuration ​

Pipeline loadI18nConfigFromFile(configPath, cwd) :

  1. Lire et analyser ai-i18n-tools.config.json (JSON).
  2. mergeWithDefaults - fusion profonde avec defaultI18nConfigPartial, et fusionner toutes les entrées docs[].sourceFiles dans contentPaths.
  3. expandTargetLocalesFileReferenceInRawInput - convertir targetLocales en tableau et rejeter les entrées de type chemin (doivent être des codes BCP-47, pas un chemin vers ui-languages.json) ; languagesManifestPath prend par défaut {ui.flatOutputDir}/ui-languages.json pendant mergeWithDefaults.
  4. expandDocumentationTargetLocalesInRawInput - idem pour chaque entrée docs[].targetLocales.
  5. expandJsonTargetLocalesInRawInput - idem pour chaque entrée json[].targetLocales.
  6. parseI18nConfig - validation Zod + validateI18nBusinessRules.
  7. applyProviderOverrideToRawInput - lorsque -P / --provider est passé sur la CLI.
  8. applyEnvOverrides - appliquer OPENROUTER_BASE_URL, OLLAMA_BASE_URL, I18N_SOURCE_LOCALE et I18N_TARGET_LOCALES si définis (les clés API sont résolues séparément par fournisseur dans LlmClient).
  9. augmentConfigWithUiLanguagesMaster - attacher les noms d'affichage du manifeste à partir du catalogue principal fourni.
  10. assertEffectiveLocalesInUiLanguagesMaster - valider les codes de locale par rapport au catalogue principal, le cas échéant.

init génère des configurations de démarrage à partir de initConfigTemplates : ui-markdown (chaînes d'interface utilisateur plus un bloc README plat), docs-markdown (README et Markdown uniquement), ui-docusaurus, ui-starlight, ui-vitepress (documentation VitePress + vitepressThemeCatalog), ui-nextra (documentation Nextra + nextraDictionaryPath), ui-astro-website (interface utilisateur Astro simple ; ajoutez docs[] pour la traduction de page .astro), ui-json-bundles (JSON json[] uniquement), ui-python, ui-python-gettext, ui-python-django, et ui-python-flask. --with-readme ajoute ce même bloc README à tout modèle qui ne liste pas déjà README.md, et active translateDocs. Voir Chaînes d'interface utilisateur — Initialiser, Ajouter l'i18n à vos documents README et Markdown, et Applications Python.

Journalisation (Logger) ​

Logger prend en charge les niveaux debug, info, warn, error avec sortie couleur ANSI. Le mode verbeux (-v) active debug. Lorsque logFilePath est défini, les lignes de journal sont également écrites dans ce fichier.

Auto-localisation (interface de l'outil) ​

L'outil localise sa propre interface utilisateur — l'aide de la CLI, les messages de journal/résumé/erreur à fort trafic et le tableau de bord de traduction — séparément du contenu qu'il traduit pour vous.

  • Résolution de la locale (resolveUiLocale dans src/core/ui-locale.ts) : sélectionne la locale de l'interface utilisateur à partir de -L / --ui-lang > AI_I18N_LANG > configuration uiLanguage > locale du système d'exploitation hôte (Intl.DateTimeFormat().resolvedOptions().locale). Le candidat est normalisé et mis en correspondance avec l'ensemble de bundles livré, soit exactement, soit par la variation la plus proche (par exemple pt-PT → pt-BR, en-US → en-GB), en revenant à la locale source (en-GB). La CLI résout une fois avant la construction de l'aide (analyse argv pré-analyse) et à nouveau après le chargement de la configuration afin que uiLanguage s'applique (le drapeau et la variable d'environnement l'emportent toujours).
  • Exécution (src/i18n/index.ts) : un t(source, vars) minimal avec interpolation {{name}}, indexé par la chaîne source anglaise par rapport à des bundles plats par locale dans src/i18n/locales/<code>.json (copiés dans dist/i18n/locales à la construction). Les clés ou bundles manquants renvoient le texte source. C'est le même modèle clé-comme-défaut que les chaînes d'interface utilisateur — il n'y a pas de recherche par hachage.
  • Tableau de bord : le serveur expose GET /api/ui-i18n renvoyant { locale, dir, bundle } pour la locale d'interface utilisateur résolue ; le frontend définit <html lang> / dir et localise le balisage statique via les attributs data-i18n*.
  • Dogfooding : les bundles sont produits par pnpm i18n:self (sync-ui --ui-block src/i18n/strings.json), qui extrait et traduit le bloc ui de la CLI et du tableau de bord dans ai-i18n-tools.config.json. Les clés de catalogue proviennent des appels t() à travers src/cli/ et src/i18n/ plus les marqueurs data-i18n* du tableau de bord dans src/dashboard-app/index.html.

Points d'extension ​

Noms de fonctions personnalisés (extraction de l'interface utilisateur) ​

Ajouter des noms de fonctions de traduction non standard via la configuration :

json
{
  "ui": {
    "uiExtractor": {
      "funcNames": ["t", "i18n.t", "translate", "i18n.translate"],
      "extensions": [".js", ".jsx", ".ts", ".tsx", ".astro", ".html"],
      "htmlI18nAttributes": ["data-i18n", "data-i18n-title", "data-i18n-placeholder", "data-i18n-alt", "data-i18n-aria-label"]
    }
  }
}

(ui.reactExtractor est un alias entièrement pris en charge pour ui.uiExtractor.)

Ajoutez .html / .htm à extensions pour analyser les attributs de marqueur HTML pendant extract. ui.uiExtractor.htmlI18nAttributes est facultatif et vaut par défaut ["data-i18n", "data-i18n-title", "data-i18n-placeholder"] ; data-i18n correspond au textContent de l'élément et data-i18n-<attr> correspond à la valeur de cet attribut (par exemple, data-i18n-aria-label).

Extracteurs personnalisés ​

Implémenter ContentExtractor depuis le package :

ts
import { BaseExtractor, type Segment } from 'ai-i18n-tools';

class MyExtractor extends BaseExtractor {
  readonly name = 'my-format';
  canHandle(filepath: string) { return filepath.endsWith('.myext'); }
  extract(content: string, filepath: string): Segment[] { /* … */ }
  reassemble(segments: Segment[], translations: Map<string, string>): string { /* … */ }
}

Enregistrez des extracteurs personnalisés en étendant les classes d'extracteurs publiques exportées depuis 'ai-i18n-tools' (par exemple, sous-classe MarkdownExtractor). La CLI connecte les extracteurs intégrés en interne ; il n'y a pas d'importation profonde prise en charge de doc-translate.ts.

Chemins de sortie personnalisés ​

Utilisez docsOutput.pathTemplate pour n’importe quelle disposition de fichiers :

json
{
  "docs": [
    {
      "docsOutput": {
        "pathTemplate": "{outputDir}/{locale}/{relativeToDocsRoot}"
      }
    }
  ]
}

Arborescence source ​

Disposition complète src/ (référence au niveau du fichier)
text
src/
├── index.ts                        Public API re-exports
│
├── cli/
│   ├── index.ts                    CLI entry point (commander)
│   ├── extract-strings.ts          `extract` command implementation
│   ├── mark-html.ts                `mark-html` command (insert bare `data-i18n*` markers into HTML)
│   ├── translate-ui-strings.ts     `translate-ui` command implementation
│   ├── doc-translate.ts            `translate-docs` command (documentation files only)
│   ├── translate-json-run.ts       `translate-json` command (`json[]` nested locale bundles)
│   ├── translate-svg.ts            `translate-svg` command (SVG files from `config.svg`)
│   ├── write-heading-ids.ts        `write-heading-ids` command (markdown heading anchors)
│   ├── bench-models.ts             `bench-models` command (per-model translate latency/token/cost benchmark)
│   ├── helpers.ts                  Shared CLI utilities
│   └── file-utils.ts               File collection helpers
│
├── markdown/
│   └── write-heading-ids-core.ts   Slug styles + `<a id="…">` insertion for `write-heading-ids`
│
├── core/
│   ├── types.ts                    Zod schemas + TypeScript types for all config shapes
│   ├── config.ts                   Config loading, merging, validation, init templates
│   ├── cache.ts                    SQLite translation cache (node:sqlite)
│   ├── prompt-builder.ts           LLM prompt construction for docs and UI strings
│   ├── output-paths.ts             Docusaurus / flat output path resolution
│   ├── ui-languages.ts             ui-languages.json loading and locale resolution
│   ├── ui-locale.ts                Resolve the tool's own UI locale (flag/env/config/OS → shipped bundle)
│   ├── locale-utils.ts             BCP-47 normalisation, locale list parsing, script/Han-variant validation
│   └── errors.ts                   Typed error classes
│
├── extractors/
│   ├── base-extractor.ts           Abstract base class for all extractors
│   ├── ui-string-extractor.ts      JS/TS and `.astro` UI scanner (Babel via `ui-string-babel.ts`)
│   ├── ui-string-babel.ts          Babel `t()` discovery (`extractUiCallsFromFileContent`)
│   ├── ui-string-locations.ts      Source locations for extracted UI strings
│   ├── html-i18n-marks.ts          HTML `data-i18n*` marker scanner + `mark-html` annotator
│   ├── classify-segment.ts         Heuristic segment type classification
│   ├── markdown-extractor.ts       Markdown / MDX segment extraction
│   ├── markdown-segment-split.ts   Optional segment splitting for long markdown blocks
│   ├── frontmatter-fields.ts       Selective YAML front matter field translation
│   ├── astro-template-extractor.ts `.astro` parse-and-replace (HTML + template expressions; used by `translate-docs`)
│   ├── json-extractor.ts           Docusaurus catalog JSON extraction (`translate-docs`)
│   ├── nested-json-extractor.ts    Arbitrary nested JSON leaves (`translate-json`, `json[]`)
│   └── svg-extractor.ts            SVG text extraction
│
├── processors/
│   ├── placeholder-handler.ts      Chain: HTML → admonitions → anchors → MDX → URLs → emphasis
│   ├── expression-attribute-protection.ts  Shared protected attribute/key lists (Astro + MDX JSX)
│   ├── url-placeholders.ts         Markdown URL protection/restore
│   ├── admonition-placeholders.ts  Docusaurus admonition protection/restore
│   ├── anchor-placeholders.ts      HTML anchor / heading ID protection/restore
│   ├── html-tag-placeholders.ts    Lowercase HTML tag / comment protection ({{HTM_N}})
│   ├── placeholder-integrity.ts    Pre/post-restore token sequence + tag-kind + invented {{IDENT}} checks
│   ├── mdx-placeholders.ts         MDX comments, JSX tags, brace expressions, JSX attribute extraction
│   ├── batch-processor.ts          Segment → batch grouping (count + char limits)
│   ├── validator.ts                Post-translation structural checks
│   └── flat-link-rewrite.ts        Relative link rewriting for flat output
│
├── api/
│   ├── llm-client.ts               LlmClient: provider-agnostic chat client (AI SDK) with model fallback chain
│   └── provider-models-catalog.ts  Fetch/parse any provider's OpenAI-compatible GET /models catalog
│
├── glossary/
│   ├── glossary.ts                 Glossary loading (CSV + auto-build from strings.json)
│   ├── matcher.ts                  Term hint extraction for prompts
│   └── translation-context.ts      contextFiles loader and guidance fingerprints
│
├── runtime/
│   ├── index.ts                    Runtime re-exports
│   ├── template.ts                 interpolateTemplate, flipUiArrowsForRtl
│   ├── ui-language-display.ts      getUILanguageLabel, getUILanguageLabelNative
│   └── i18next-helpers.ts          RTL detection, i18next setup factories
│
├── i18n/                           Self-localisation runtime for the tool's own UI
│   ├── index.ts                    t(source, vars) + bundle/manifest loaders (keyed by English source string)
│   └── locales/                    Shipped UI bundles (de.json, es.json, …; generated by `pnpm i18n:self`)
│
├── dashboard-app/
│   ├── index.html                  Translation Dashboard static UI (HTML/CSS/JS)
│   ├── app.js
│   └── styles.css
│
├── server/
│   └── translation-dashboard.ts    Express app for Translation Dashboard (cache / strings.json / glossary)
│
└── utils/
    ├── logger.ts                   Leveled logger with ANSI support
    ├── hash.ts                     Segment hash (SHA-256 first 16 hex)
    ├── table.ts                    Display-width aware table rendering (CJK/emoji column alignment)
    ├── load-dotenv.ts              Load `.env` / `.env.local` beside the config when no API key is set
    └── ignore-parser.ts            .translate-ignore file parser

Publié sous licence MIT.