Saltar al contenido
verbatra

Docs / Primeros pasos / Inicio rápido

Página traducida automáticamente

Esta página se tradujo automáticamente, así que puede contener errores o sonar un poco rara. La versión en inglés es la fuente de la verdad. Leer el original en inglés.

Inicio rápido con Flutter

Traduce con verbatra los archivos de locale de ARB de tu app de Flutter, desde la instalación hasta el primer texto en alemán en pantalla.

Al final de esta página, tu app de Flutter muestra un texto en alemán que verbatra tradujo desde lib/l10n/app_en.arb, y un archivo de bloqueo hace que cada ejecución posterior traduzca solo lo que cambió. Necesitas Node.js ^22.18.0 || >=24, un proyecto de Flutter y unos diez minutos. Los primeros cuatro pasos no necesitan cuenta ni clave de API.

¿Ya tienes archivos de locale y un agente de programación? Dale en su lugar el prompt de Configura verbatra con un agente de IA: trabaja con los archivos que tu proyecto ya tiene y se detiene antes de gastar nada.

Pasos

Instala la CLI

npm install --save-dev @verbatra/cli

verbatra es una herramienta de desarrollo y nunca llega a tu app. Los comandos de abajo usan npx; con pnpm, yarn o bun, ejecuta pnpm verbatra, yarn verbatra o bun run verbatra.

Una app de Flutter no tiene package.json

Tu gestor de paquetes crea uno en la primera instalación. Añade node_modules/ a tu .gitignore.

Añade un archivo de locale de origen

Si lib/l10n/app_en.arb ya existe, sáltate este paso. Si no, créalo con dos textos, uno de ellos con un marcador de posición:

lib/l10n/app_en.arb
{
  "@@locale": "en",
  "greeting": "Hello, {name}!",
  "@greeting": {
    "placeholders": { "name": { "type": "String" } }
  },
  "cartEmpty": "Your cart is empty."
}

Genera una configuración

npx @verbatra/cli init --format arb --provider gemini --yes

--format arb es el formato de archivo de flutter_localizations. init encuentra tus archivos de locale, o escribe el patrón lib/l10n/app_{locale}.arb cuando aún no hay ninguno. --yes acepta lo que init detectó en lugar de preguntar. El nuevo verbatra.config.ts traduce de en a de; añade códigos a targetLocales para más idiomas.

Previsualiza la ejecución sin clave

npx @verbatra/cli translate --dry-run
Salida
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)

Una ejecución de prueba no construye ningún proveedor, así que no necesita clave, no gasta nada y no escribe nada.

Traduce

cp .env.example .env

Abre .env y pega tu clave después de GEMINI_API_KEY=. ¿Aún no tienes clave? Gemini tiene un nivel gratuito: crea una en Google AI Studio. Los demás proveedores y sus variables están en Proveedores.

npx @verbatra/cli translate

verbatra envía los dos textos a Gemini, comprueba que cada marcador de posición sobrevive y escribe lib/l10n/app_de.arb. El texto depende del modelo, por ejemplo:

lib/l10n/app_de.arb
{
  "@@locale": "de",
  "greeting": "Hallo, {name}!",
  "cartEmpty": "Dein Warenkorb ist leer."
}

Comprueba que cada locale está sincronizado

npx @verbatra/cli check
Salida
[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 puede proteger un pull request.

Carga los locales en tu app

Añade flutter_localizations:

flutter pub add flutter_localizations:"{sdk: flutter}" intl:any

Después carga ambos archivos y muestra el saludo:

pubspec.yaml
flutter:
  generate: true
l10n.yaml
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
lib/main.dart
import 'package:flutter/material.dart';
import 'l10n/app_localizations.dart';

void main() => runApp(
  MaterialApp(
    locale: const Locale('de'),
    localizationsDelegates: AppLocalizations.localizationsDelegates,
    supportedLocales: AppLocalizations.supportedLocales,
    home: Builder(
      builder: (context) => Text(AppLocalizations.of(context)!.greeting('Ada')),
    ),
  ),
);

Arranca tu app: el saludo dice Hallo, Ada!.

Qué acaba de pasar

  • verbatra.lock.json guarda un hash de cada texto de origen, para que la siguiente ejecución envíe solo textos nuevos y modificados. Consulta El archivo de bloqueo.
  • Un resultado que pierde un marcador de posición se retiene y nunca se escribe. Consulta Seguridad de la traducción.

Haz commit de los archivos de locale, verbatra.lock.json y verbatra.provenance.json juntos.

Opcional: conecta tu agente de programación Disponible a partir de 0.12.0

npx @verbatra/cli init --agent

Con la configuración ya creada, init --agent la conserva y añade solo los archivos del agente: las reglas de verbatra en AGENTS.md (o CLAUDE.md, cuando es tu único archivo de instrucciones) y el servidor MCP de verbatra, sin las herramientas que gastan, en la configuración de proyecto de cada agente de programación que detecta. Qué archivos escribe para cada agente, y cómo eliges tú los agentes con --client, está en Preparar los agentes de programación. --dry-run muestra los archivos sin escribirlos.

O, sin la CLI, añade solo el servidor MCP a tu perfil de usuario de VS Code; usa una vía, nunca las dos:

Añadir a VS Code

Siguiente

Añadir un idioma

Añade un locale de destino y deja que una ejecución lo complete.

Ejecutar verbatra en CI

Haz fallar un pull request cuando un locale se desvía.

Elige tu stack

El id de formato y la estructura de archivos de cualquier otro framework.

Editar en GitHub

En esta página

PasosInstala la CLIAñade un archivo de locale de origenGenera una configuraciónPrevisualiza la ejecución sin claveTraduceComprueba que cada locale está sincronizadoCarga los locales en tu appQué acaba de pasarOpcional: conecta tu agente de programaciónSiguiente