verbatra extract

Empieza por tu código en lugar de por un archivo de locale. extract recorre las raíces de código que configuras, encuentra en ellas las llamadas de traducción y añade cada clave que el archivo del locale de origen todavía no tiene. Así verbatra sirve en un proyecto que aún no está internacionalizado, y no gasta nada: ni proveedor, ni clave de API, ni petición de red.

SinopsisCopiar enlace a esta sección

verbatra extract [flags]

EjemplosCopiar enlace a esta sección

# add every new key found in your source to the source locale file
verbatra extract

# preview the keys that would be added, write nothing
verbatra extract --dry-run

# machine-readable result for a CI step
verbatra extract --json

FlagsCopiar enlace a esta sección

También acepta los flags globales --cwd, --config y --json; las raíces de código de extract se resuelven desde la raíz del proyecto.

ComportamientoCopiar enlace a esta sección

ConfiguraciónCopiar enlace a esta sección

extract se rige por el bloque extract de tu configuración. Una ejecución sin él falla con EXTRACT_NOT_CONFIGURED y sale con 2. Para i18next-json, verbatra init escribe el bloque como comentario en la configuración generada; quítale el comentario y ajusta roots.

import { defineConfig } from "@verbatra/cli";

export default defineConfig({
  sourceLocale: "en",
  targetLocales: ["de", "fr"],
  format: "i18next-json",
  files: { pattern: "locales/{locale}.json" },
  provider: { id: "gemini", options: { model: "gemini-2.5-flash", maxOutputTokens: 4096 } },
  extract: {
    framework: "i18next",
    roots: ["src"],
  },
});

Qué encuentraCopiar enlace a esta sección

El framework i18next lee las formas de llamada t(...), $t(...) y <object>.t(...) en archivos .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts y .cts, cada una también como llamada opcional y con una lista explícita de argumentos de tipo. La clave es el primer argumento; un valor por defecto es el segundo argumento o un campo defaultValue en el objeto de opciones:

t("nav.home");                              // key only, written with an empty value
t("nav.away", "Away");                      // positional default
t("nav.help", { defaultValue: "Help" });    // default on the options object
t?.("nav.back");                            // optional call
t<string>("nav.next");                      // explicit type argument

Se entienden los comentarios, las cadenas y las expresiones regulares, así que no se recoge una llamada dentro de un comentario ni un t( entre comillas dentro de una cadena. La clave y el valor por defecto deben ser cada uno un literal completo: t("user." + id) se informa como dinámica, y un valor por defecto concatenado añade la clave sin valor por defecto en lugar de con uno truncado. Una clave con un segmento de ruta vacío (t("user."), t(".lead"), t("a..b")) acabaría bajo un hijo sin nombre que tu aplicación nunca lee, así que también se informa como dinámica.

Los namespaces todavía no se resuelvenCopiar enlace a esta sección

Una clave con namespace como t("common:nav.home") se informa como dinámica y nunca se escribe: una configuración de verbatra direcciona un solo archivo de catálogo, así que no hay ningún sitio que signifique lo que tu configuración de i18next quiere decir. Si tu proyecto nombra un namespace en cada llamada, la ejecución no añade nada. Hoy extract es útil en un proyecto que mantiene un solo namespace y escribe sus claves sin el prefijo.

Qué escribeCopiar enlace a esta sección

Solo el archivo del locale de origen, y solo claves realmente nuevas:

• Una clave que ya está en el catálogo conserva su valor tal cual; un valor por defecto en la llamada nunca sobrescribe una edición.
• Una clave que el catálogo solo tiene en formas de plural cuenta como presente: t("cart.items", { count }) no añade nada junto a cart.items_one y cart.items_other, y lo mismo vale para una entrada gettext con msgid_plural y un recurso <plurals> de Android. En un formato que no marca las formas de plural, como YAML, cuenta toda clave que termina en un sufijo de plural de i18next.
• Una clave del catálogo que ninguna llamada menciona se queda donde está. extract nunca borra; verbatra diff --unused lista esas claves.
• Una ejecución que no encuentra nada nuevo no escribe nada, así que el archivo queda idéntico byte a byte.
• Nunca se escribe un archivo de locale de destino. Ejecuta después verbatra translate para rellenar las claves nuevas. Una clave añadida con valor vacío se omite hasta que escribas su texto de origen, y la ejecución la nombra con SOURCE_VALUE_EMPTY.

Los catálogos xliff y apple-xcstrings nunca se crean desde cero: crea primero el catálogo de origen (el de .xcstrings en Xcode) y extract lo amplía después.

Qué informa en lugar de adivinarCopiar enlace a esta sección

Todo lo que el análisis no puede resolver vuelve como datos, así que un archivo incómodo nunca aborta una ejecución. Nada de esto cambia el código de salida.

Límites del análisisCopiar enlace a esta sección

No se lee nada fuera de las roots configuradas. node_modules, .git, .next, .turbo, .verbatra, dist, build y coverage se omiten siempre, extract.exclude añade tus propios nombres de directorio y no se siguen los enlaces simbólicos. El resultado lleva solo claves, valores y ubicaciones de archivo y línea, nunca el contenido de un archivo de código.

Salida JSONCopiar enlace a esta sección

Esquema: extract-envelope.json valida el envoltorio completo; Esquemas enumera los demás.

Con --json, el envoltorio lleva un resultado:

interface ExtractResult {
  sourcePath: string;          // the source locale file, relative to the project root
  scannedFiles: number;
  added: { key: string; value: string; file: string; line: number }[];
  existingKeys: number;        // keys found that were already in the catalog
  withoutDefault: string[];
  dynamic: { file: string; line: number }[];
  conflicts: { key: string; values: string[]; locations: { file: string; line: number }[] }[];
  diagnostics: { file: string; reason: "unreadable" | "too-large" | "unparseable" | "unreadable-directory" }[];
  written: boolean;            // false for a dry run and for a run that added nothing
  dryRun: boolean;
}

Información en el terminalCopiar enlace a esta sección

El resumen va a stdout. En stderr, una línea de spinner cuenta los archivos analizados; si se añadieron claves, una sugerencia propone verbatra translate, o tras --dry-run el mismo extract sin el flag. --quiet omite las líneas de stderr:

verbatra: scanning the source... done (0.6s)
verbatra extract
  42 files scanned, 18 keys already present
  added 3 keys to locales/en.json
  new keys (3):
    nav.home  src/components/Nav.tsx:14
    nav.away  src/components/Nav.tsx:15
    cart.empty  src/routes/cart.tsx:31
  dynamic keys (1):
    src/routes/product.tsx:88
next: verbatra translate (translate the new keys)

Consulta Salida en el terminal para el color, el spinner y las variables que los controlan.

Códigos de salidaCopiar enlace a esta sección

No hay salida 1: las llamadas dinámicas y los valores por defecto en conflicto son hallazgos, no fallos. Consulta Códigos de salida para el contrato que sigue cada comando.

RelacionadoCopiar enlace a esta sección

• Extrae claves del código fuente recorre el flujo desde la llamada hasta la clave traducida.
• El archivo de configuración documenta el bloque extract.
• verbatra translate rellena los locales de destino una vez que existen las claves nuevas.
• verbatra types declara las claves para TypeScript.
• verbatra check informa del desfase que crean las claves nuevas.
• El SDK ofrece la misma capacidad como extract().