---
title: "Démarrage rapide"
description: "Installe la CLI, génère une configuration, prévisualise l'exécution sans clé d'API et traduis ton premier fichier de locale."
type: "tutorial"
---
# Démarrage rapide

Installe la CLI, génère une configuration, prévisualise l'exécution sans clé d'API et traduis ton premier fichier de locale.

À la fin de cette page, un fichier de locale anglais a un pendant allemand, écrit par un fournisseur et vérifié par verbatra, ainsi que le fichier de verrouillage grâce auquel chaque exécution suivante ne traduit que ce qui a changé. Il te faut Node.js `^22.18.0 || >=24` et une dizaine de minutes. Les quatre premières étapes ne demandent ni compte ni clé d'API.

<Callout title="Tu as déjà des fichiers de locale et un agent de code ?">
Donne à ton agent le prompt de [Configure verbatra avec un agent IA](https://verbatra.kreitz-webdev.de/fr/docs/start-with-ai.md). Il installe verbatra autour des fichiers de locale que ton projet a déjà et s'arrête avant de dépenser quoi que ce soit. Les étapes ci-dessous partent de zéro.
</Callout>

Un démarrage rapide qui charge aussi le fichier traduit dans ton app existe pour [React](https://verbatra.kreitz-webdev.de/fr/docs/quickstart/react.md), [Next.js](https://verbatra.kreitz-webdev.de/fr/docs/quickstart/nextjs.md), [Vue](https://verbatra.kreitz-webdev.de/fr/docs/quickstart/vue.md), [Angular](https://verbatra.kreitz-webdev.de/fr/docs/quickstart/angular.md) et [Flutter](https://verbatra.kreitz-webdev.de/fr/docs/quickstart/flutter.md).

## Étapes [#étapes]

<Steps>
<Step>

### Installe la CLI [#installe-la-cli]

```bash
npm install --save-dev @verbatra/cli
```

Les commandes ci-dessous utilisent `npx`. Avec pnpm, yarn ou bun, lance plutôt `pnpm verbatra`, `yarn verbatra` ou `bun run verbatra`. Si pnpm s'arrête avec `ERR_PNPM_IGNORED_BUILDS`, consulte le [dépannage](https://verbatra.kreitz-webdev.de/fr/docs/troubleshooting.md#pnpm-bloque-les-scripts-dinstallation-dune-dépendance-err_pnpm_ignored_builds).

</Step>
<Step>

### Ajoute un fichier de locale source [#ajoute-un-fichier-de-locale-source]

Si ton projet a déjà des fichiers de locale, passe cette étape. Sinon, crées-en un :

```json title="locales/en.json"
{
  "greeting": "Hello, {{name}}!",
  "cart": {
    "empty": "Your cart is empty."
  }
}
```

</Step>
<Step>

### Génère une configuration [#génère-une-configuration]

```bash
npx @verbatra/cli init --format i18next-json --provider gemini --yes
```

`--format` indique le format de tes fichiers : [Choisis ta stack](https://verbatra.kreitz-webdev.de/fr/docs/pick-your-stack.md) donne l'id pour chaque framework. `--yes` reprend ce que `init` a détecté au lieu de poser des questions ; sans lui, tu réponds aux questions que liste [`verbatra init`](https://verbatra.kreitz-webdev.de/fr/docs/cli/init.md).

```text output
created verbatra.config.ts
created .env.example
created .gitignore (.env, .env.local, .verbatra-local/, verbatra.cache.json)
detected format i18next-json, pattern locales/{locale}.json, locales en (confidence: medium)
next steps:
  - Copy .env.example to .env and set GEMINI_API_KEY there. Never commit .env.
  - npx @verbatra/cli doctor  (Check the setup. It calls no provider and reads no key value.)
  - npx @verbatra/cli translate --dry-run  (Preview what a run would translate, without calling the provider.)
```

Le nouveau `verbatra.config.ts` traduit de `en` vers `de`. Ajoute des codes à `targetLocales` pour d'autres langues.

</Step>
<Step>

### Prévisualise l'exécution sans clé [#prévisualise-lexécution-sans-clé]

```bash
npx @verbatra/cli translate --dry-run
```

```text output
verbatra: dry run over 1 locale, no provider call
verbatra: de done, 2 would translate
verbatra translate (dry run)
  de: 2 would translate, 0 unchanged
1 succeeded, 0 partial, 0 failed (dry run: nothing written)
[ok] dry run done in 0.0s, nothing written
next: verbatra translate (run it for real)
```

Voici la forme dans un terminal interactif ; dans un pipe ou en CI, chaque étape a aussi sa propre ligne, voir [Sortie dans le terminal](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#sortie-dans-le-terminal). Une exécution à blanc ne construit aucun fournisseur : elle n'a pas besoin de clé, ne dépense rien et n'écrit rien. [`verbatra doctor`](https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md) vérifie le reste de la configuration de la même façon.

</Step>
<Step>

### Traduis [#traduis]

```bash
cp .env.example .env
```

Ouvre `.env` et colle ta clé après `GEMINI_API_KEY=`. Les clés viennent uniquement de l'environnement, et la CLI y charge [`.env.local` et `.env`](https://verbatra.kreitz-webdev.de/fr/docs/cli.md#fichiers-denvironnement). Pas encore de clé ? Gemini a une offre gratuite : crées-en une dans [Google AI Studio](https://aistudio.google.com/apikey). Les autres fournisseurs et leurs variables sont sur [Fournisseurs](https://verbatra.kreitz-webdev.de/fr/docs/providers.md).

```bash
npx @verbatra/cli translate
```

verbatra envoie les deux clés manquantes à Gemini, vérifie chaque résultat et écrit le fichier allemand. Le résumé commence par `de: 2 translated, 0 unchanged` et indique les tokens utilisés par l'exécution. La formulation dépend du modèle, par exemple :

```json title="locales/de.json"
{
  "greeting": "Hallo, {{name}}!",
  "cart": {
    "empty": "Dein Warenkorb ist leer."
  }
}
```

</Step>
<Step>

### Vérifie que chaque locale est synchronisée [#vérifie-que-chaque-locale-est-synchronisée]

```bash
npx @verbatra/cli check
```

```text output
[ok] checking the locales (0.0s)
verbatra check
  de: 0 missing, 0 stale, 2 up-to-date (in sync)
all locales in sync
```

`check` n'appelle aucun fournisseur et se termine avec `1` dès qu'une locale n'est plus synchronisée : la même commande peut donc protéger une pull request.

</Step>
</Steps>

## Ce qui vient de se passer [#ce-qui-vient-de-se-passer]

- `locales/de.json` contient les mêmes clés dans le même ordre que ta source, et `{{name}}` a survécu : un résultat qui perd un placeholder est retenu, jamais écrit. Voir [Sûreté de la traduction](https://verbatra.kreitz-webdev.de/fr/docs/translation-safety.md).
- `verbatra.lock.json` enregistre un hash du texte source derrière chaque traduction, pour que l'exécution suivante n'envoie que les clés nouvelles ou modifiées. Voir [Le fichier de verrouillage](https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md).
- `verbatra.provenance.json` note quel fournisseur et quel modèle a écrit chaque valeur. Voir [La provenance](https://verbatra.kreitz-webdev.de/fr/docs/the-lock-file.md#la-provenance-de-chaque-valeur).
- `verbatra.cache.json` et `.verbatra-local/` contiennent le cache de traduction régénérable et l'état local de l'exécution. `init` les a déjà ajoutés au `.gitignore`. Voir [Le cache](https://verbatra.kreitz-webdev.de/fr/docs/the-cache.md).

Commite ensemble les fichiers de locale, le fichier de verrouillage et le fichier de provenance, pour que chaque machine et ta CI comparent avec la même base.

## Ensuite [#ensuite]

<Cards>
  <Card title="Ajouter une langue" href="https://verbatra.kreitz-webdev.de/fr/docs/add-a-language.md" description="Ajoute une locale cible et laisse une exécution la remplir." />
  <Card title="Exécuter verbatra en CI" href="https://verbatra.kreitz-webdev.de/fr/docs/ci-and-exit-codes.md" description="Fais échouer une pull request quand une locale dérive." />
  <Card title="Comment fonctionne une exécution" href="https://verbatra.kreitz-webdev.de/fr/docs/how-it-works.md" description="Le pipeline derrière les commandes que tu viens de lancer." />
  <Card title="Fichier de configuration" href="https://verbatra.kreitz-webdev.de/fr/docs/config-file.md" description="Tout ce que verbatra.config.ts peut contenir." />
</Cards>