---
order: 4
section: guides
title: Traducción
description: >-
  Cómo funciona la traducción en scribe: control de versiones mediante hash,
  Gemini, validación de resultados, informes de costes y herramientas de
  revisión.
noindex: false
canonicalPath: /es/docs/translation
---
Scribe traduce el texto original en inglés a todos los demás idiomas utilizando un LLM (Gemini) y almacena los resultados en SQLite. No hace falta editar los archivos de cada idioma. Simplemente editas el inglés, vuelves a ejecutar `scribe translate` y confirmas los cambios en el almacén de datos.

## Qué se traduce

Por cada documento, se envían exactamente dos elementos al traductor:

1. Los campos del frontmatter marcados con `field.translatable()`, incluyendo aquellos anidados en arrays y objetos.
2. El cuerpo en formato MDX.

Todo lo demás (`field.structural()`, relaciones, campos integrados) se copia del documento en inglés en el momento de la carga. Si utilizas `slugStrategy: "localized"`, el traductor también generará un slug de URL para cada idioma (en formato kebab-case ASCII, transliterado para alfabetos no latinos).

Un idioma que aún no hayas traducido no supondrá un problema en el entorno de ejecución. La función `resolve()` ofrece la traducción más cercana disponible a través de la [cadena de alternativas de idioma](/docs/configuration#locale-fallback-chains) (por ejemplo, `pt-BR` recurre a `pt` y luego al idioma predeterminado), lo que te permite implementar nuevos idiomas de forma progresiva.

## Control de contenido obsoleto

Cada traducción almacenada guarda un hash SHA-256 del contenido traducible en inglés del que procede. El comando `scribe translate` solo vuelve a traducir una página cuando:

- no existe ninguna traducción para ese idioma (**falta**), o
- el contenido traducible en inglés ha cambiado desde la última vez (**obsoleto**).

Modificar un campo estructural o una entrada en `_redirects.json` **no** marca las traducciones como obsoletas, ya que esos campos no se traducen.

## Validación de resultados

Una traducción solo se guarda definitivamente si supera dos comprobaciones:

1. El cuerpo MDX devuelto debe poder analizarse correctamente (después de normalizar los errores de escape y las comillas de los atributos JSX, en los que el modelo a veces falla).
2. El frontmatter devuelto debe volver a validarse de acuerdo con tu esquema completo de Zod.

Los elementos que no superan la validación se vuelven a intentar automáticamente una vez al final del proceso. Para ello, se envían los errores de validación al modelo para que pueda corregirlos (las ejecuciones por lotes se reintentan como un trabajo por lotes adicional, manteniendo la tarifa de lotes). Todo lo que vuelva a fallar aparecerá en el resumen final junto con su nuevo error, y el comando devolverá un código de salida distinto de cero. Los resultados incorrectos del modelo nunca llegan al almacén de datos, por lo que jamás llegarán a producción.

## Cómo ejecutarlo

```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
```

Al ejecutarlo en una terminal, `scribe translate` muestra una interfaz de progreso en directo con el estado de los trabajos por lotes, los resultados por elemento, el recuento de tokens en curso y el coste estimado en dólares. Los tokens de razonamiento se incluyen en el uso notificado, por lo que la estimación coincide con lo que factura Google. Pasa el parámetro `--no-progress` (o ejecútalo de forma no interactiva, por ejemplo en un entorno de integración continua) para obtener un registro de texto línea por línea.

El parámetro `--dry-run` imprime la lista de tareas y no escribe nada, informando de un recuento estimado de tokens y un coste en dólares por elemento y en los totales, calculados a partir del prompt real y el tamaño de la carga útil en inglés. Si se usa `--batch`, la estimación aplica el descuento por lotes, por lo que permite prever lo que costará la ejecución real.

A continuación, confirma los cambios en `.scribe/store.sqlite`.

## Modo por lotes y reanudación

Por defecto, toda la lista de tareas se procesa a través de la API Gemini Batch, que funciona a un 50% del coste por token de las llamadas directas. Scribe planifica cada petición por adelantado (un trabajo por modelo, dividido en fragmentos para listas de tareas muy largas), envía todos los trabajos a la vez, los sondea conjuntamente y almacena los resultados de cada trabajo en el instante en que finaliza. Los trabajos por lotes suelen terminar en cuestión de minutos, pero Google solo garantiza su finalización en un plazo de 24 horas, así que el comando espera en lugar de transmitir los resultados página a página.

Cada trabajo se registra en el almacén de SQLite antes de que empiece el sondeo, junto con una instantánea de la fuente en inglés desde la que se envió cada elemento. Esto hace que sea seguro interrumpir las ejecuciones:

- Puedes salir durante el sondeo (Ctrl+C) y no se perderá nada.
- El comando `scribe translate --resume` comprueba los trabajos pendientes, asimila los terminados y no envía nada nuevo.
- La ejecución normal de `scribe translate` también retoma primero los trabajos pendientes, y los elementos que ya están en curso nunca se envían dos veces.
- No hay problema en editar una página en inglés mientras su lote está en proceso. El resultado se guarda junto a la instantánea a partir de la cual se tradujo, y luego se detecta como obsoleto en la siguiente ejecución.

¿Prefieres resultados inmediatos página a página pagando el precio completo? Utiliza `--direct`, que restablece las llamadas a la API por página con el paralelismo de `--concurrency`. En una terminal, el selector interactivo ofrece esta misma opción. Los errores transitorios de la API (429, 5xx, cortes de red) se reintentan automáticamente con un retroceso exponencial en ambos modos.

## Cómo guiar al traductor

El prompt integrado está diseñado en torno a la transcreación y no a la traducción literal. El modelo escribe como un redactor nativo que crea la edición localizada. Recrea modismos y juegos de palabras en lugar de traducirlos literalmente, y aplica convenciones tipográficas nativas (comillas, apóstrofos, espaciado de puntuación). Tu `context`, `rules` y `prompt` se superponen a ese marco de trabajo.

Valores predeterminados de todo el proyecto y anulaciones por tipo:

```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.",
        ],
      },
    }),
  ],
});
```

| Opción | Alcance | Descripción |
| --- | --- | --- |
| `context` | proyecto + tipo | Contexto de marca o dominio que se antepone a cada petición (los contextos de proyecto y tipo se concatenan). |
| `rules` | proyecto + tipo | Reglas adicionales que se añaden a las predeterminadas. |
| `prompt` | proyecto o tipo | Instrucciones adicionales de localización, que se anteponen a la directiva del idioma de destino (el nombre y el código del idioma se añaden siempre al final). |
| `defaultModel` / `model` | proyecto / tipo | Identificador del modelo de Gemini. Valor por defecto: `gemini-3.1-pro` (también se puede anular mediante la variable de entorno `PROSE_GEMINI_MODEL` o con `--model`). |

Las reglas integradas (que siempre se aplican) incluyen: no traducir los nombres de marcas a menos que tengan un nombre local muy conocido en el mercado de destino, devolver los cuerpos MDX con saltos de línea reales (no con el escape `\n`), y arreglar las comillas de los atributos JSX cuando los valores contienen comillas dobles.

## Revisión de traducciones

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

Cada traducción enlaza con una instantánea del texto original en inglés a partir del cual se elaboró (almacenada en el mismo archivo de SQLite). Esto permite auditar cuándo, a partir de qué y con qué modelo se tradujo una página. El comando `scribe history` imprime esa línea de tiempo; el estudio muestra la cobertura por idioma, la lista actual de tareas pendientes u obsoletas, y el detalle por documento con la instantánea junto a la traducción almacenada.

## Ajustes preestablecidos de idiomas

Para implementaciones graduales, puedes asignar nombres a grupos de idiomas en la configuración y seleccionarlos con `--preset`:

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

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