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  providerOptions: {13    ollama: {14      think: true,15    },16  },17  messages: {18    entry: "./src/messages/en.json",19  },20});

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. 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});

Ejemplos

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

CLI