CLI

Usa @better-translate/cli cuando quieras que Better Translate cree y actualice archivos de locale por ti.

No necesitas la CLI para usar los paquetes de runtime. Es opcional.

1. Instalar el paquete

npm install -D @better-translate/cli

La CLI no depende de un proveedor concreto. Tu app instala y configura el paquete del proveedor del AI SDK directamente.

2. Crear un archivo de locale fuente

Crea src/messages/en.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 rellene.

3. Crear la configuración de la 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 en su lugar, como @ai-sdk/openai, @ai-sdk/anthropic o @ai-sdk/moonshotai.

La URL por defecto de la API de Ollama es local: http://localhost:11434/api.

Funciona igual con proveedores alojados como OpenAI, Anthropic y Moonshot AI. La CLI ya no incluye helpers de proveedores.

4. Marcar 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 runtime, { bt: true } devuelve la cadena sin cambios. La CLI sustituirá esas llamadas por claves correctas en la siguiente extracción.

También puedes pasar otras opciones como params; se conservan tras la extracción:

1// Escribes:2t("Hello world", { bt: true })3t("Hello {name}", { bt: true, params: { name: "" } })45// Tras bt extract, el archivo queda reescrito:6t("components.nav.helloWorld")7t("components.nav.helloName", { params: { name: "" } })

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

5. Extraer claves fuente

npx bt extract

Esto busca llamadas t(..., { bt: true }), añade las claves que falten al archivo de locale fuente y reescribe las llamadas a claves estrictas simples.

La CLI encuentra automáticamente better-translate.config.ts en la raíz del proyecto. El flag --config solo hace falta si tu archivo de configuración está en otra ubicación.

6. Ejecutar el generador

npx bt generate

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

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

npx bt generate --yes

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

7. Eliminar claves no usadas

npx bt purge

Esto escanea 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 locale. Te pide confirmar cada clave antes de borrarla:

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

Escribe y para eliminar una clave de todos los archivos de locale, o n (o solo Enter) para conservarla.

Para eliminar todas las claves no usadas de una vez sin preguntar:

npx bt purge --yes

Para ver qué se eliminaría sin escribir cambios:

npx bt purge --dry-run

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

8. Usar los archivos generados en tu app

Cuando los archivos existan, impórtalos en tu configuración de @better-translate/core igual que cualquier archivo de locale 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

Ejemplos

Ejemplos completos en el repositorio de GitHub:

• nextjs-example
• react-vite-example
• core-elysia-example