Guía de Agentes: Usar champollion

champollion es una herramienta CLI que traduce los archivos de configuración regional de su aplicación con un solo comando. Esta guía es para agentes de IA (o desarrolladores que trabajan con agentes de IA) que desean pasar de cero a archivos de configuración regional traducidos rápidamente.

:::tip ¿Ya está familiarizado? Si solo necesita comandos, vaya a la Referencia CLI. Si desea construir y comparar un método de traducción, consulte la Guía de Agentes de Arena. :::

Configuración del Entorno

# No global install needed — npx runs it directly
npx champollion sync

Requisitos:

Node.js 18+
Una clave de API para su proveedor de traducción

Configuración de clave de API — champollion necesita al menos una clave dependiendo de qué métodos utilice:

# Option 1: export (session only)
export OPENROUTER_API_KEY="sk-or-..."        # for llm / llm-coached methods
export GOOGLE_TRANSLATE_API_KEY="AIza..."    # for google-translate method

# Option 2: .env file in your project root (persistent, gitignored)
echo 'OPENROUTER_API_KEY=sk-or-...' > .env

Champollion lee .env automáticamente. Obtenga una clave de OpenRouter en openrouter.ai/keys.

Primera Sincronización

Champollion detecta automáticamente sus archivos de configuración regional, su formato (JSON, TOML, YAML, PO) e idiomas de destino:

npx champollion sync

Lo que sucede:

Carga champollion.config.json (o detecta automáticamente la configuración)
Escanea su archivo de configuración regional de origen, aplana las claves anidadas
Compara con .champollion.lock (hashes SHA-256 de valores previamente traducidos)
Verifica .champollion/tm.json para traducciones en caché (Memoria de Traducción)
Traduce solo claves cambiadas, faltantes o antiguas mediante el método configurado
Ejecuta la puerta de calidad (5 verificaciones) en cada traducción
Escribe las traducciones aprobadas en el archivo de configuración regional de destino
Actualiza el archivo de bloqueo y la caché de TM

En una re-ejecución típica después de cambiar una clave, el paso 4 sirve 142 claves desde caché y el paso 5 traduce 1 clave. Por eso las sincronizaciones posteriores son rápidas y económicas.

Configuración

Cree champollion.config.json en la raíz de su proyecto:

{
  "inputLocale": "en",
  "pairs": {
    "en-fr": { "method": "llm-coached" },
    "en-ja": { "method": "google-translate" },
    "en-crk": { "method": "api", "endpoint": "http://localhost:3000/translate" }
  }
}

Campos clave:

Campo	Propósito	Predeterminado
`inputLocale`	Idioma de origen	`en`
`pairs`	Mapa de origen→destino con configuración de método	(requerido)
`localesDir`	Dónde viven los archivos de configuración regional	(detectado automáticamente)
`model`	Modelo LLM para métodos `llm`/`llm-coached`	`google/gemini-2.5-flash`
`batchSize`	Claves por llamada de API	80 (LLM), 128 (Google)
`jsonConcurrency`	Traducciones paralelas de configuración regional para claves JSON	200
`contentConcurrency`	Llamadas de API paralelas para traducción de contenido	48

Referencia completa: Configuración

Métodos de Traducción

Método	Cuándo usar	Costo	Clave de API necesaria
`llm`	Propósito general, bueno para idiomas bien dotados de recursos	Por token (depende del modelo)	`OPENROUTER_API_KEY`
`llm-coached`	Cuando tiene reglas gramaticales/diccionario para el idioma de destino	Por token + contexto de coaching	`OPENROUTER_API_KEY`
`google-translate`	Idiomas de alto recurso donde GT funciona bien	$20/millones de caracteres	`GOOGLE_TRANSLATE_API_KEY`
`api`	Canalización personalizada alojada detrás de un punto final HTTP	Determinado por servidor	Ninguno (el punto final maneja la autenticación)
`plugin`	Método preempaquetado instalado localmente	Varía	Varía

Detalles: Métodos de Traducción

Datos de Coaching

Para pares llm-coached, los datos de coaching guían el LLM con conocimiento lingüístico explícito. Cree un archivo de coaching:

coaching/fr.json
{
  "grammar_rules": [
    "Use formal register (vous) for all UI text",
    "Adjectives agree in gender and number with the noun"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms."
}

Haga referencia a él en la configuración de su par:

"en-fr": { "method": "llm-coached", "coachingFile": "coaching/fr.json" }

La puerta de calidad verifica que los términos del diccionario realmente aparezcan en la salida — las violaciones se registran como advertencias [TERM].

Detalles: Datos de Coaching

Puerta de Calidad

Cada traducción pasa por cinco verificaciones automatizadas antes de escribirse en disco:

Verificación	Qué detecta	Ejemplo
Vacío/en blanco	El modelo no devolvió nada	`""`
Eco de origen	El modelo devolvió la entrada en inglés sin cambios	`"Welcome"` para japonés
Bucle de alucinación	Trigramas repetidos	`"Qo' Qo' Qo' Qo'"`
Inflación de longitud	La salida es 4 veces o más larga que la fuente	Fuente de 10 caracteres → salida de 50 caracteres
Cumplimiento de script	Script incorrecto para la configuración regional	Texto latino para configuración regional árabe

Los fallos se registran con prefijo [GATE]. Sin respaldos silenciosos — si una traducción falla, se reporta, no se acepta silenciosamente.

Detalles: Puerta de Calidad

Memoria de Traducción

Champollion almacena en caché las traducciones en .champollion/tm.json, indexadas por texto de origen + configuración regional + método. En sincronizaciones posteriores, las claves sin cambios se sirven desde caché — sin llamada de API, sin costo.

[TM] 142 key(s) served from cache
Translating 3 key(s) to French (llm)... [OK]

Para omitir la caché en una ejecución: npx champollion sync --no-tm

Detalles: Memoria de Traducción

Archivos Generados

Champollion crea varios archivos en su proyecto. Sepa qué son para no eliminar o confirmar accidentalmente los incorrectos:

Archivo	Propósito	¿Git?
`.champollion.lock`	Hashes SHA-256 de valores de origen traducidos (detección de cambios)	Sí — confirme esto
`.champollion-content.lock`	Lo mismo, pero para archivos de contenido Markdown/MDX	Sí — confirme esto
`.champollion/tm.json`	Caché de Memoria de Traducción	Sí — confirme esto (ahorra costos de API para el equipo)
`.champollion/coaching/`	Directorio de datos de coaching	Sí — este es su conocimiento lingüístico
`champollion.config.json`	Configuración del proyecto	Sí — confirme esto

Patrones Comunes

Traducir un par de idiomas:

npx champollion sync --pair en-fr

Traducir todos los pares configurados:

npx champollion sync

Champollion traduce todas las configuraciones regionales en paralelo. Con almacenamiento en caché de TM, solo las claves cambiadas llegan a la API.

Modo de contenido (Markdown/MDX para Docusaurus, Hugo, etc.):

npx champollion sync --content

Traduce documentos, publicaciones de blog y archivos de contenido junto con JSON de configuración regional. Utiliza concurrencia paralela (predeterminado: 48 llamadas de API simultáneas). Ajuste con --content-concurrency.

Ejecución en seco (vista previa sin escribir):

npx champollion sync --dry-run

Forzar re-traducción de claves específicas:

npx champollion sync --force-keys "hero.title,nav.about"

Forzar re-traducción de todos los archivos de contenido:

npx champollion sync --force-content

Verificar estado de traducción:

npx champollion status

Muestra cobertura, niveles de calidad e información de complementos para cada par.

Auditar respaldos sin traducir:

npx champollion audit

Enumera todos los valores de respaldo [EN] que necesitan traducción.

Solución de Problemas

Problema	Solución
`OPENROUTER_API_KEY not set`	Exporte la clave o agréguela a `.env` en la raíz de su proyecto
`No locale files found`	Establezca `localesDir` en la configuración, o asegúrese de que sus archivos de configuración regional coincidan con la nomenclatura estándar (`en.json`, `fr.json`)
`[GATE] Script compliance failed`	Su configuración regional de destino obtuvo texto latino en lugar del script esperado — intente un modelo diferente o agregue datos de coaching
`[GATE] Source echo`	El modelo devolvió inglés sin cambios — los datos de coaching o un modelo diferente generalmente lo arreglan
Todas las traducciones en caché	Ejecute con `--no-tm` para omitir la caché, o `--force-keys` para claves específicas
Conflictos de archivo de bloqueo	`.champollion.lock` utiliza hashes SHA-256 — los conflictos de fusión son seguros de resolver manteniendo cualquier versión, luego re-ejecutando la sincronización

Próximos Pasos

Inicio Rápido — tutorial completo de introducción
Referencia CLI — cada comando y bandera
Cómo Funciona — la canalización de sincronización explicada
El Puente del Arnés de Evaluación — cómo champollion se conecta a Arena
¿Desea construir su propio método de traducción? Consulte la Guía de Agentes de Arena — construya un método, demuestre que funciona, gane premios.

Configuración del Entorno​

Primera Sincronización​

Configuración​

Métodos de Traducción​

Datos de Coaching​

Puerta de Calidad​

Memoria de Traducción​

Archivos Generados​

Patrones Comunes​

Solución de Problemas​

Próximos Pasos​