CLI

Usa @better-translate/cli cuando quieras que Better Translate construya y actualice los archivos de idioma por ti.

No necesitas el CLI para usar los paquetes de tiempo de ejecución. Es opcional.

1. Instala el paquete

npm install -D @better-translate/cli

El CLI permanece agnóstico al proveedor. Tu aplicación instala y configura el paquete de proveedor del AI SDK directamente.

2. Crea un archivo de idioma fuente

Crea src/messages/en.json:

json

1{2  "home": {3    "title": "Hello",4    "description": "Welcome to the app"5  }6}

También puedes empezar con un {} vacío y dejar que bt extract lo complete.

3. Crea la configuración del CLI

Crea better-translate.config.ts:

1import { createOllama } from "ollama-ai-provider-v2";2import { defineConfig } from "@better-translate/cli/config";34const ollama = createOllama({5  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/api",6});78export default defineConfig({9  sourceLocale: "en",10  locales: ["es", "fr"],11  model: ollama("qwen3:4b"),12  messages: {13    entry: "./src/messages/en.json",14  },15});

Si usas Ollama, instala ollama-ai-provider-v2. Si usas un proveedor alojado, instala ese paquete de proveedor en su lugar, como @ai-sdk/openai, @ai-sdk/anthropic o @ai-sdk/moonshotai.

La URL de API predeterminada de Ollama es local: http://localhost:11434/api.

Esto funciona igual con proveedores alojados como OpenAI, Anthropic y Moonshot AI. El CLI ya no incluye helpers de proveedores.

4. Marca cadenas en tu código

En lugar de nombrar claves de traducción a mano, escribe el texto fuente directamente y añade { bt: true }:

1import { t } from "@better-translate/core";23export function navLabel() {4  return t("Home", { bt: true });5}

En tiempo de ejecución, { bt: true } devuelve la cadena sin cambios. El CLI reemplazará estas llamadas con claves apropiadas en la siguiente extracción.

También puedes pasar otras opciones como params — se conservan después de la extracción:

1// Escribes:2t("Hello world", { bt: true })3t("Hello {name}", { bt: true, params: { name: "" } })45// Después de que bt extract reescriba el archivo:6t("components.nav.helloWorld")7t("components.nav.helloName", { params: { name: "" } })

El espacio de nombres de la clave proviene de la ruta del archivo fuente (components/nav.tsx → components.nav). bt: true siempre se elimina al reescribir.

5. Extrae las claves fuente

npx bt extract

Esto busca llamadas a t(..., { bt: true }), añade las claves faltantes a tu archivo de idioma fuente y reescribe las llamadas con claves estrictas simples.

El CLI encuentra automáticamente better-translate.config.ts en la raíz de tu proyecto. La bandera --config solo es necesaria si tu archivo de configuración está en una ubicación diferente.

6. Ejecuta el generador

npx bt generate

Esto crea los archivos de idioma de destino junto a tu archivo fuente.

Si markdown.rootDir está habilitado y la ejecución crearía o sobrescribiría archivos .md o .mdx traducidos, el CLI solicita confirmación antes de realizar cambios. Usa --yes o -y para omitir el mensaje:

npx bt generate --yes

Las ejecuciones no interactivas que necesiten escribir archivos markdown traducidos deben pasar --yes.

7. Elimina claves sin uso

npx bt purge

Esto analiza tu código en busca de claves de traducción que ya no aparecen en ninguna llamada t("...") y las elimina de todos los archivos de idioma. El CLI te pide confirmación para cada clave de forma individual antes de eliminarla:

tsx

1? Purge unused key "home.oldTitle"? (y/N) y2? Purge unused key "sidebar.legacy"? (y/N) n

Escribe y + Enter para eliminar una clave de todos los archivos de idioma, o n + Enter (o simplemente Enter) para conservarla.

Para eliminar todas las claves sin uso de una vez sin confirmación:

npx bt purge --yes

Para previsualizar qué se eliminaría sin realizar ningún cambio:

npx bt purge --dry-run

Claves dinámicas: Si tu código usa una clave dinámica como t(`section.${id}`), el CLI no puede resolverla estáticamente. Te avisará, protegerá las claves que compartan el prefijo detectado o marcará la clave como insegura y la omitirá en lugar de eliminarla silenciosamente si aún puede estar en uso.

8. Usa los archivos generados en tu aplicación

Después de que los archivos existen, impórtalos en tu configuración de @better-translate/core igual que cualquier archivo de idioma escrito a mano.

Markdown

Si también quieres generación de markdown localizado, añade la opción markdown.rootDir:

1import { createOllama } from "ollama-ai-provider-v2";2import { defineConfig } from "@better-translate/cli/config";34const ollama = createOllama({5  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/api",6});78export default defineConfig({9  sourceLocale: "en",10  locales: ["es", "fr"],11  model: ollama("qwen3:4b"),12  messages: {13    entry: "./src/messages/en.json",14  },15  markdown: {16    rootDir: "./content/docs",17  },18});

Referencia de comandos

Comando	Bandera	Descripción
`bt extract`		Busca llamadas `bt: true`, sincroniza el idioma fuente, reescribe las llamadas
	`--config <ruta>`	Ruta al archivo de configuración (detectado automáticamente por defecto)
	`--dry-run`	Previsualiza los cambios sin escribir
	`--max-length <n>`	Longitud máxima de segmento para nombres de claves generados
`bt generate`		Traduce el idioma fuente a todos los archivos de idioma de destino
	`--config <ruta>`	Ruta al archivo de configuración
	`--dry-run`	Previsualiza los cambios sin escribir
	`--yes`, `-y`	Omite la confirmación para escrituras de archivos markdown
`bt purge`		Elimina las claves de traducción sin uso de todos los archivos de idioma
	`--config <ruta>`	Ruta al archivo de configuración
	`--dry-run`	Previsualiza qué claves se eliminarían sin escribir
	`--yes`, `-y`	Elimina todas las claves sin uso sin confirmación

Ejemplos

Los ejemplos completos funcionando están en el repositorio de GitHub:

CLI