---
title: "verbatra extract"
description: "Analyse le code de ton application à la recherche des appels de traduction et ajoute les nouvelles clés au fichier de la locale source."
type: "reference"
---
# verbatra extract
Analyse le code de ton application à la recherche des appels de traduction et ajoute les nouvelles clés au fichier de la locale source.
.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 :
```ts
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("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ésolus [#les-espaces-de-noms-ne-sont-pas-encore-résolus]
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 écrit [#ce-quelle-écrit]
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 ``. 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`](https://verbatra.kreitz-webdev.de/fr/docs/cli/diff.md#clés-source-inutilisées) 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`](https://verbatra.kreitz-webdev.de/fr/docs/cli/translate.md) 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`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#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 deviner [#ce-quelle-signale-plutôt-que-de-deviner]
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.
| Signalé comme | Quand |
| --- | --- |
| `dynamic` | la clé n'est pas une seule chaîne statique complète, ou désigne un chemin que verbatra ne peut pas adresser : une variable, une expression membre, un littéral de gabarit avec une expression, une concaténation, une clé avec espace de noms ou un segment de chemin vide. Elle n'est jamais écrite. |
| `conflicts` | une clé apparaît dans deux appels avec des valeurs par défaut différentes. Aucune valeur n'est écrite, pour que le catalogue ne dépende jamais de l'ordre de parcours. |
| `withoutDefault` | une clé a été ajoutée avec une valeur vide parce que son appel n'avait pas de valeur par défaut. Remplis-la, puis traduis. |
| `diagnostics` | un fichier ou un répertoire n'a pas pu être lu jusqu'au bout : il a disparu, dépasse la limite de 2 000 000 octets, l'analyse a échoué dessus, ou un commentaire, littéral de gabarit, élément JSX ou chaîne non fermé a abandonné la suite. Ce qui a été lu avant ce point est quand même signalé. |
### Limites de l'analyse [#limites-de-lanalyse]
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 JSON [#sortie-json]
Schéma : [`extract-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/extract-envelope.json) valide l'enveloppe entière ; [Schémas](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#schémas) liste les autres.
Avec `--json`, l'[enveloppe](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#sortie-json) porte un résultat :
```ts
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 terminal [#retour-dans-le-terminal]