¿Cómo configuro el CLI y escaneo mi proyecto?

El CLI de Better i18n es una herramienta para desarrolladores que escanea tu base de código en busca de claves de traducción y las mantiene sincronizadas con el panel.

Instalación

# Con bun (recomendado)
bun add -g @better-i18n/cli

# Con npm
npm install -g @better-i18n/cli

# Con pnpm
pnpm add -g @better-i18n/cli

Verifica la instalación:

better-i18n --version

Autenticación

Inicia sesión con tu cuenta de Better i18n:

better-i18n login

Esto abre una ventana del navegador para la autenticación. Tus credenciales se almacenan local y de forma segura.

Configuración del proyecto

Crea un archivo de configuración en la raíz de tu proyecto:

better-i18n init

Esto genera better-i18n.config.ts:

import { defineConfig } from '@better-i18n/cli';

export default defineConfig({
  project: 'acme/dashboard',
  sourceLocale: 'en',
  // Directorios a escanear para claves de traducción
  include: ['src/**/*.{ts,tsx,js,jsx}'],
  // Directorios a excluir
  exclude: ['node_modules', 'dist', '.next'],
});

Escanear tu base de código

Ejecuta el escáner para encontrar todas las claves de traducción:

better-i18n scan

El escáner detecta:

• t('key') — llamadas estándar de función de traducción
• t('namespace:key') — claves con espacio de nombres
• useTranslations('namespace') — importaciones de espacio de nombres
• Literales de plantilla: t(`key.${dynamic}`) (reportado como clave dinámica)

Resultado del escaneo

Scanning src/**/*.{ts,tsx}...

 Found 142 translation keys in 38 files
   • common: 24 keys
   • auth: 18 keys
   • dashboard: 45 keys
   • settings: 32 keys
   • (default): 23 keys

 ⚠ 3 dynamic keys detected (review manually)

Sincronizar con el panel

Envía las claves escaneadas a Better i18n:

better-i18n sync

Esto:

1. Compara las claves locales con el panel
2. Crea las nuevas claves que aún no existen
3. Reporta las claves que existen en el panel pero no en el código (posibles claves muertas)

Verificar el estado de sincronización

Verifica que todo esté sincronizado:

better-i18n check

✓ 142 keys in sync
⚠ 3 keys in code but not in dashboard (run sync to fix)
⚠ 5 keys in dashboard but not in code (potential dead keys)

Ejecutar doctor

Diagnostica problemas comunes:

better-i18n doctor

Esto verifica tu configuración, autenticación, conectividad API y configuración del proyecto.

Integración CI/CD

Agrega better-i18n check a tu pipeline de CI para detectar traducciones faltantes antes de hacer merge:

# Ejemplo de GitHub Actions
- name: Check translations
  run: better-i18n check --strict

La bandera --strict sale con código 1 si alguna clave no está sincronizada.

Próximos pasos

• Configurar el SDK de Next.js
• Agregar tus primeras claves de traducción