verbatra extract

Pars de ton code plutôt que d'un fichier de locale. extract parcourt les racines de sources que tu configures, y trouve les appels de traduction et ajoute chaque clé que le fichier de la locale source n'a pas encore. verbatra devient ainsi utilisable sur un projet pas encore internationalisé, sans rien dépenser : ni fournisseur, ni clé d'API, ni requête réseau.

SynopsisCopier le lien vers cette section

verbatra extract [flags]

ExemplesCopier le lien vers cette section

# add every new key found in your source to the source locale file
verbatra extract

# preview the keys that would be added, write nothing
verbatra extract --dry-run

# machine-readable result for a CI step
verbatra extract --json

OptionsCopier le lien vers cette section

Accepte aussi les options globales --cwd, --config et --json ; les racines de sources d'extract sont résolues depuis la racine du projet.

ComportementCopier le lien vers cette section

ConfigurationCopier le lien vers cette section

extract est piloté par le bloc extract de ta configuration. Une exécution sans lui échoue avec EXTRACT_NOT_CONFIGURED et la sortie 2. Pour i18next-json, verbatra init écrit le bloc en commentaire dans la configuration générée ; décommente-le et ajuste roots.

import { defineConfig } from "@verbatra/cli";

export default defineConfig({
  sourceLocale: "en",
  targetLocales: ["de", "fr"],
  format: "i18next-json",
  files: { pattern: "locales/{locale}.json" },
  provider: { id: "gemini", options: { model: "gemini-2.5-flash", maxOutputTokens: 4096 } },
  extract: {
    framework: "i18next",
    roots: ["src"],
  },
});

Ce qu'elle trouveCopier le lien vers cette section

Le framework i18next lit les formes d'appel t(...), $t(...) et <object>.t(...) dans les fichiers .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts et .cts, chacune aussi en appel optionnel et avec une liste explicite d'arguments de type. La clé est le premier argument ; une valeur par défaut est le deuxième argument ou un champ defaultValue de l'objet d'options :

t("nav.home");                              // key only, written with an empty value
t("nav.away", "Away");                      // positional default
t("nav.help", { defaultValue: "Help" });    // default on the options object
t?.("nav.back");                            // optional call
t<string>("nav.next");                      // explicit type argument

Les commentaires, les chaînes et les expressions régulières sont compris : un appel dans un commentaire ou un t( entre guillemets dans une chaîne n'est pas retenu. La clé et la valeur par défaut doivent chacune être un littéral complet : t("user." + id) est signalé comme dynamique, et une valeur par défaut concaténée ajoute la clé sans valeur par défaut plutôt qu'avec une valeur tronquée. Une clé avec un segment de chemin vide (t("user."), t(".lead"), t("a..b")) atterrirait sous un enfant sans nom que ton application ne lit jamais, elle est donc aussi signalée comme dynamique.

Les espaces de noms ne sont pas encore résolusCopier le lien vers cette section

Une clé avec espace de noms comme t("common:nav.home") est signalée comme dynamique et jamais écrite : une configuration verbatra adresse un seul fichier de catalogue, il n'existe donc aucun endroit qui signifie ce que ta configuration i18next entend par là. Si ton projet nomme un espace de noms à chaque appel, l'exécution n'ajoute rien. Aujourd'hui, extract est utile sur un projet qui garde un seul espace de noms et écrit ses clés sans préfixe.

Ce qu'elle écritCopier le lien vers cette section

Uniquement le fichier de la locale source, et uniquement des clés vraiment nouvelles :

• Une clé déjà présente dans le catalogue garde sa valeur telle quelle ; une valeur par défaut dans un appel n'écrase jamais une modification.
• Une clé que le catalogue ne contient que sous ses formes plurielles compte comme présente : t("cart.items", { count }) n'ajoute rien à côté de cart.items_one et cart.items_other, et il en va de même pour une entrée gettext avec msgid_plural et une ressource Android <plurals>. Dans un format qui ne marque pas les formes plurielles, comme YAML, toute clé terminée par un suffixe de pluriel i18next compte.
• Une clé du catalogue qu'aucun appel ne mentionne reste en place. extract ne supprime jamais rien ; verbatra diff --unused liste ces clés.
• Une exécution qui ne trouve rien de nouveau n'écrit rien, le fichier reste donc identique à l'octet près.
• Aucun fichier de locale cible n'est écrit. Lance ensuite verbatra translate pour remplir les nouvelles clés. Une clé ajoutée avec une valeur vide est ignorée tant que tu n'as pas écrit son texte source, et l'exécution la nomme avec SOURCE_VALUE_EMPTY.

Les catalogues xliff et apple-xcstrings ne sont jamais créés à partir de rien : crée d'abord le catalogue source (celui en .xcstrings dans Xcode), puis extract le complète.

Ce qu'elle signale plutôt que de devinerCopier le lien vers cette section

Tout ce que l'analyse ne peut pas résoudre revient sous forme de données, donc un fichier récalcitrant n'interrompt jamais une exécution. Rien de tout cela ne change le code de sortie.

Limites de l'analyseCopier le lien vers cette section

Rien en dehors des roots configurées n'est lu. node_modules, .git, .next, .turbo, .verbatra, dist, build et coverage sont toujours ignorés, extract.exclude ajoute tes propres noms de répertoires, et les liens symboliques ne sont pas suivis. Le résultat ne porte que des clés, des valeurs et des emplacements de fichier et de ligne, jamais le contenu d'un fichier source.

Sortie JSONCopier le lien vers cette section

Schéma : extract-envelope.json valide l'enveloppe entière ; Schémas liste les autres.

Avec --json, l'enveloppe porte un résultat :

interface ExtractResult {
  sourcePath: string;          // the source locale file, relative to the project root
  scannedFiles: number;
  added: { key: string; value: string; file: string; line: number }[];
  existingKeys: number;        // keys found that were already in the catalog
  withoutDefault: string[];
  dynamic: { file: string; line: number }[];
  conflicts: { key: string; values: string[]; locations: { file: string; line: number }[] }[];
  diagnostics: { file: string; reason: "unreadable" | "too-large" | "unparseable" | "unreadable-directory" }[];
  written: boolean;            // false for a dry run and for a run that added nothing
  dryRun: boolean;
}

Retour dans le terminalCopier le lien vers cette section

Le résumé va sur stdout. Sur stderr, une ligne de spinner compte les fichiers analysés ; si des clés ont été ajoutées, une suggestion propose verbatra translate, ou après --dry-run le même extract sans l'option. --quiet supprime les lignes de stderr :

verbatra: scanning the source... done (0.6s)
verbatra extract
  42 files scanned, 18 keys already present
  added 3 keys to locales/en.json
  new keys (3):
    nav.home  src/components/Nav.tsx:14
    nav.away  src/components/Nav.tsx:15
    cart.empty  src/routes/cart.tsx:31
  dynamic keys (1):
    src/routes/product.tsx:88
next: verbatra translate (translate the new keys)

Consulte Sortie dans le terminal pour la couleur, le spinner et les variables qui les contrôlent.

Codes de sortieCopier le lien vers cette section

Il n'y a pas de sortie 1 : les appels dynamiques et les valeurs par défaut en conflit sont des constats, pas des échecs. Consulte Codes de sortie pour le contrat que suit chaque commande.

Voir aussiCopier le lien vers cette section

• Extraire les clés du code source parcourt le déroulé, de l'appel à la clé traduite.
• Le fichier de configuration documente le bloc extract.
• verbatra translate remplit les locales cibles une fois les nouvelles clés en place.
• verbatra types déclare les clés pour TypeScript.
• verbatra check signale l'écart que les nouvelles clés créent.
• Le SDK expose la même capacité sous le nom extract().