---
order: 4
section: guides
title: Traduction
description: >-
  Découvrez le fonctionnement de scribe translate : hachage d'obsolescence,
  Gemini, validation des sorties, suivi des coûts et outils de révision.
noindex: false
canonicalPath: /fr/docs/translation
---
Scribe s'appuie sur un grand modèle linguistique (Gemini) pour traduire vos contenus en anglais vers toutes les autres langues, puis stocke les résultats dans SQLite. Inutile de modifier les fichiers de traduction manuellement. Vous éditez simplement l'anglais, relancez `scribe translate` et commitez la base.

## Ce qui est traduit

Pour chaque document, l'outil de traduction ne reçoit que deux éléments précis :

1. Les champs du frontmatter marqués `field.translatable()`, y compris ceux imbriqués dans des tableaux ou des objets.
2. Le corps du fichier MDX.

Tout le reste (`field.structural()`, les relations, les champs natifs) est directement copié du document en anglais lors du chargement. Si vous utilisez `slugStrategy: "localized"`, le traducteur génère également un slug d'URL propre à chaque langue (en kebab-case ASCII, avec translittération pour les alphabets non latins).

Une langue non traduite ne pose aucun problème en production : `resolve()` affiche la traduction disponible la plus proche en suivant la [chaîne de repli des langues](/docs/configuration#locale-fallback-chains) (par exemple, `pt-BR` se rabat sur `pt`, puis sur la langue par défaut). Vous pouvez ainsi déployer vos langues progressivement.

## Suivi des mises à jour

Chaque traduction sauvegardée inclut une empreinte SHA-256 du contenu anglais traduisible dont elle découle. `scribe translate` ne retraduit une page que dans deux cas :

- la langue ne possède pas encore de traduction (**missing**), ou
- le contenu traduisible en anglais a été modifié depuis la dernière fois (**stale**).

Modifier un champ structurel ou une entrée du fichier `_redirects.json` ne rend **pas** les traductions obsolètes, car ces éléments échappent au processus de traduction.

## Validation des résultats

Une traduction n'est enregistrée que si elle passe deux vérifications avec succès :

1. Le code MDX généré doit pouvoir être analysé (après correction des erreurs d'échappement et des guillemets dans les attributs JSX que le modèle gère parfois mal).
2. Le frontmatter généré doit repasser la validation complète de votre schéma Zod.

En cas d'échec, les éléments concernés font l'objet d'une nouvelle tentative automatique à la fin du cycle. Les erreurs de validation sont transmises au modèle pour qu'il puisse s'auto-corriger (les exécutions par lots relancent un job supplémentaire, toujours au tarif batch). Si l'échec persiste, l'élément s'affiche dans le résumé final accompagné de sa nouvelle erreur et la commande se termine avec un code d'erreur. Les mauvaises réponses du modèle n'atteignent jamais la base de données et ne risquent donc pas de se retrouver en production.

## Lancement des commandes

```bash
export GEMINI_API_KEY=...        # also read from .env / .env.local

scribe status                     # coverage per type and locale
scribe translate                  # interactive picker in a TTY
scribe translate --locale fr de   # specific locales
scribe translate --preset active  # a localePresets group from the config
scribe translate --type blog      # one content type (comma-separated: --type blog,glossary)
scribe translate --slug my-post   # one document
scribe translate --dry-run        # show the worklist + est. tokens/cost, write nothing
scribe translate --force          # re-translate even when hashes match
scribe translate --strategy missing-only   # skip stale, only fill gaps
scribe translate --batch          # force batch mode (the default)
scribe translate --direct         # per-page API calls, immediate results
scribe translate --resume         # pick up pending batch jobs, submit nothing new
scribe translate --concurrency 5  # parallel requests (direct mode only)
scribe translate --model gemini-3.1-pro
```

Lancée dans un terminal, la commande `scribe translate` affiche une interface de progression en direct. Vous y trouverez le statut des jobs par lots, les résultats élément par élément, le décompte des tokens en cours et une estimation du coût en dollars américains. Les tokens de réflexion sont inclus dans l'utilisation affichée, l'estimation correspond donc exactement à la facturation de Google. Ajoutez `--no-progress` (ou exécutez la commande en mode non interactif, comme dans une CI) pour obtenir un simple journal ligne par ligne.

L'option `--dry-run` liste le travail à effectuer sans rien écrire. Elle fournit une estimation du nombre de tokens et du coût en dollars par élément ainsi qu'au global, calculée à partir du prompt réel et de la taille du contenu anglais. Avec `--batch`, l'estimation applique la réduction liée au traitement par lots, ce qui vous donne un aperçu très précis du coût réel de l'exécution.

Il ne vous reste plus qu'à commiter `.scribe/store.sqlite`.

## Mode batch et reprise

Par défaut, l'ensemble de la liste de travail passe par l'API Gemini Batch, qui permet de réduire de moitié le coût en tokens par rapport aux appels directs. Scribe planifie chaque requête à l'avance (un job par modèle, fragmenté pour les très longues listes), soumet tous les jobs simultanément, puis interroge leur statut de manière globale et enregistre les résultats de chaque job dès qu'il est terminé. Ces jobs se terminent généralement en quelques minutes, mais Google ne garantit leur exécution que dans un délai de 24 heures. La commande patiente donc au lieu d'afficher les résultats page par page.

Chaque job est inscrit dans la base SQLite avant le début de l'interrogation, avec un instantané de la source anglaise pour chaque élément soumis. Vous pouvez donc interrompre l'exécution en toute sécurité :

- Quittez pendant la phase d'interrogation (Ctrl+C) et aucune donnée ne sera perdue.
- `scribe translate --resume` vérifie les jobs en attente, intègre ceux qui sont terminés et ne soumet aucune nouvelle requête.
- Un lancement classique de `scribe translate` commence par reprendre les jobs en attente. Les éléments déjà en cours de traitement ne sont jamais soumis une seconde fois.
- Vous pouvez tout à fait modifier une page en anglais pendant que son lot est en cours de traitement. Le résultat est associé à l'instantané utilisé pour la traduction, puis marqué comme obsolète lors de l'exécution suivante.

Vous préférez obtenir des résultats immédiats, page par page, au tarif plein ? Utilisez `--direct` pour rétablir les appels d'API par page avec le parallélisme défini par `--concurrency`. Dans un terminal, le sélecteur interactif vous propose exactement la même option. Les erreurs d'API temporaires (429, 5xx, coupures réseau) bénéficient d'une nouvelle tentative automatique avec un délai d'attente exponentiel, quel que soit le mode choisi.

## Orientation du traducteur

Le prompt natif privilégie la transcréation plutôt qu'une traduction littérale. Le modèle rédige comme un concepteur-rédacteur local s'occupant de l'adaptation : il recrée les expressions idiomatiques et les jeux de mots au lieu de les traduire mot à mot. Il applique aussi les règles typographiques locales (guillemets, apostrophes, espacement de la ponctuation). Vos paramètres `context`, `rules` et `prompt` viennent s'ajouter à ce cadre de base.

Valeurs par défaut du projet et exceptions par type de contenu :

```ts
export default defineConfig({
  translate: {
    context: "MyBrand is a B2B SaaS. Never translate the brand name MyBrand.",
    rules: ["Keep numbers and statistics accurate."],
  },
  types: [
    defineContentType({
      id: "blog",
      // ...
      translate: {
        rules: [
          "Preserve all MDX/JSX component tags, props, and URLs exactly.",
          "Translate link anchor text; never change href paths.",
        ],
      },
    }),
  ],
});
```

| Option | Portée | Description |
| --- | --- | --- |
| `context` | projet + type | Contexte de la marque ou du domaine ajouté au début de chaque requête (les contextes du projet et du type sont combinés). |
| `rules` | projet + type | Règles supplémentaires ajoutées aux paramètres par défaut. |
| `prompt` | projet ou type | Instructions de localisation supplémentaires, placées avant la directive de la langue cible (le nom et le code de la langue sont toujours inclus). |
| `defaultModel` / `model` | projet / type | Identifiant du modèle Gemini. Par défaut : `gemini-3.1-pro` (peut également être écrasé via la variable d'environnement `PROSE_GEMINI_MODEL` ou l'option `--model`). |

Les règles natives (toujours appliquées) incluent les éléments suivants : ne pas traduire les noms de marque (sauf s'ils possèdent une appellation locale très connue sur le marché cible), renvoyer le code MDX avec de vrais sauts de ligne (et non des `\n` échappés), et corriger les guillemets des attributs JSX lorsque les valeurs comportent des guillemets doubles.

## Révision des traductions

```bash
scribe history blog my-post fr    # EN snapshot timeline for one page
scribe studio                     # read-only web UI on :3600
```

Chaque traduction est reliée à un instantané de la source anglaise d'origine (sauvegardé dans le même fichier SQLite). Vous pouvez ainsi vérifier quand la page a été traduite, à partir de quel contenu et avec quel modèle. La commande `scribe history` affiche cet historique. Le studio indique la couverture par langue, la liste actuelle des éléments manquants ou obsolètes, et un niveau de détail par document avec l'instantané affiché à côté de la traduction stockée.

## Préréglages de langues

Pour des déploiements progressifs, vous pouvez nommer des groupes de langues dans la configuration et les cibler avec l'option `--preset` :

```ts
localePresets: {
  active: ["fr", "es", "ja"],
  ultraLight: ["fr"],
}
```

```bash
scribe translate --preset ultraLight
```