---
title: "Inicio rápido"
description: "Instala la CLI, genera una configuración, previsualiza la ejecución sin clave de API y traduce tu primer archivo de locale."
type: "tutorial"
---
# Inicio rápido

Instala la CLI, genera una configuración, previsualiza la ejecución sin clave de API y traduce tu primer archivo de locale.

Al final de esta página, un archivo de locale en inglés tiene un hermano en alemán, escrito por un proveedor y comprobado por verbatra, además del archivo de bloqueo que hace que cada ejecución posterior traduzca solo lo que cambió. Necesitas Node.js `^22.18.0 || >=24` y unos diez minutos. Los primeros cuatro pasos no necesitan cuenta ni clave de API.

<Callout title="¿Ya tienes archivos de locale y un agente de programación?">
Dale a tu agente el prompt de [Configura verbatra con un agente de IA](https://verbatra.kreitz-webdev.de/es/docs/start-with-ai.md). Configura verbatra en torno a los archivos de locale que tu proyecto ya tiene y se detiene antes de gastar nada. Los pasos de abajo empiezan desde cero.
</Callout>

Hay un inicio rápido que además carga el archivo traducido en tu app para [React](https://verbatra.kreitz-webdev.de/es/docs/quickstart/react.md), [Next.js](https://verbatra.kreitz-webdev.de/es/docs/quickstart/nextjs.md), [Vue](https://verbatra.kreitz-webdev.de/es/docs/quickstart/vue.md), [Angular](https://verbatra.kreitz-webdev.de/es/docs/quickstart/angular.md) y [Flutter](https://verbatra.kreitz-webdev.de/es/docs/quickstart/flutter.md).

## Pasos [#pasos]

<Steps>
<Step>

### Instala la CLI [#instala-la-cli]

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

Los comandos de abajo usan `npx`. Con pnpm, yarn o bun, ejecuta `pnpm verbatra`, `yarn verbatra` o `bun run verbatra`. Si pnpm termina con `ERR_PNPM_IGNORED_BUILDS`, consulta [Solución de problemas](https://verbatra.kreitz-webdev.de/es/docs/troubleshooting.md#pnpm-bloquea-los-scripts-de-instalación-de-una-dependencia-err_pnpm_ignored_builds).

</Step>
<Step>

### Añade un archivo de locale de origen [#añade-un-archivo-de-locale-de-origen]

Si tu proyecto ya tiene archivos de locale, sáltate este paso. Si no, crea uno:

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

</Step>
<Step>

### Genera una configuración [#genera-una-configuración]

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

`--format` indica el formato de tus archivos: [Elige tu stack](https://verbatra.kreitz-webdev.de/es/docs/pick-your-stack.md) tiene el id de cada framework. `--yes` acepta lo que `init` detectó en lugar de preguntar; sin él, respondes a las preguntas que enumera [`verbatra init`](https://verbatra.kreitz-webdev.de/es/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.)
```

El nuevo `verbatra.config.ts` traduce de `en` a `de`. Añade códigos a `targetLocales` para más idiomas.

</Step>
<Step>

### Previsualiza la ejecución sin clave [#previsualiza-la-ejecución-sin-clave]

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

Esta es la forma en un terminal interactivo; con una tubería o en CI, cada paso tiene además su propia línea, consulta [Salida en el terminal](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#salida-en-el-terminal). Una ejecución de prueba no construye ningún proveedor, así que no necesita clave, no gasta nada y no escribe nada. [`verbatra doctor`](https://verbatra.kreitz-webdev.de/es/docs/cli/doctor.md) comprueba el resto de la configuración de la misma forma.

</Step>
<Step>

### Traduce [#traduce]

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

Abre `.env` y pega tu clave después de `GEMINI_API_KEY=`. Las claves solo vienen del entorno, y la CLI carga en él [`.env.local` y `.env`](https://verbatra.kreitz-webdev.de/es/docs/cli.md#archivos-de-entorno). ¿Aún no tienes clave? Gemini tiene un nivel gratuito: crea una en [Google AI Studio](https://aistudio.google.com/apikey). Los demás proveedores y sus variables están en [Proveedores](https://verbatra.kreitz-webdev.de/es/docs/providers.md).

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

verbatra envía las dos claves que faltan a Gemini, comprueba cada resultado y escribe el archivo en alemán. El resumen empieza con `de: 2 translated, 0 unchanged` e indica los tokens que usó la ejecución. El texto depende del modelo, por ejemplo:

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

</Step>
<Step>

### Comprueba que cada locale está sincronizado [#comprueba-que-cada-locale-está-sincronizado]

```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` no llama a ningún proveedor y termina con `1` en cuanto un locale deja de estar sincronizado, así que el mismo comando puede proteger un pull request.

</Step>
</Steps>

## Qué acaba de pasar [#qué-acaba-de-pasar]

- `locales/de.json` tiene las mismas claves en el mismo orden que tu origen, y `{{name}}` sobrevivió: un resultado que pierde un marcador de posición se retiene y nunca se escribe. Consulta [Seguridad de la traducción](https://verbatra.kreitz-webdev.de/es/docs/translation-safety.md).
- `verbatra.lock.json` guarda un hash del texto de origen detrás de cada traducción, para que la siguiente ejecución envíe solo claves nuevas y modificadas. Consulta [El archivo de bloqueo](https://verbatra.kreitz-webdev.de/es/docs/the-lock-file.md).
- `verbatra.provenance.json` registra qué proveedor y qué modelo escribió cada valor. Consulta [Procedencia](https://verbatra.kreitz-webdev.de/es/docs/the-lock-file.md#procedencia-quién-escribió-cada-valor).
- `verbatra.cache.json` y `.verbatra-local/` contienen la caché de traducción regenerable y el estado local de la ejecución. `init` ya los añadió a `.gitignore`. Consulta [La caché](https://verbatra.kreitz-webdev.de/es/docs/the-cache.md).

Haz commit de los archivos de locale, el archivo de bloqueo y el archivo de procedencia juntos, para que cada máquina y tu CI comparen contra la misma base.

## Siguiente [#siguiente]

<Cards>
  <Card title="Añadir un idioma" href="https://verbatra.kreitz-webdev.de/es/docs/add-a-language.md" description="Añade un locale de destino y deja que una ejecución lo complete." />
  <Card title="Ejecutar verbatra en CI" href="https://verbatra.kreitz-webdev.de/es/docs/ci-and-exit-codes.md" description="Haz fallar un pull request cuando un locale se desvía." />
  <Card title="Cómo funciona una ejecución" href="https://verbatra.kreitz-webdev.de/es/docs/how-it-works.md" description="El pipeline detrás de los comandos que acabas de ejecutar." />
  <Card title="Archivo de configuración" href="https://verbatra.kreitz-webdev.de/es/docs/config-file.md" description="Todo lo que puede contener verbatra.config.ts." />
</Cards>