Libro de recetas: Traducir 30 idiomas

Escale un proyecto de un puñado de locales a cobertura global. Este libro de recetas lo guía a través de la selección de métodos, optimización de costos e integración de CI para un despliegue multiidioma real.

Escenario: Tiene una aplicación SaaS con en, fr, es. Necesita agregar 27 idiomas más en tres niveles de requisitos de calidad.

---

Paso 1: Categorizar sus idiomas

No todos los 30 idiomas necesitan el mismo enfoque. Agrúpelos por calidad de método disponible:

Nivel	Idiomas	Método	Por qué
Nivel 1 — Premium	ja, ko, zh, de, pt	llm (GPT-4o)	Mercados de alto valor, gramática matizada
Nivel 2 — Estándar	it, nl, pl, sv, da, fi, no, cs, ro, hu, el, tr, id, ms, th, vi, uk, bg	google-translate	Alto volumen, bien soportado por Google
Nivel 3 — Entrenado	crk, oj, mi, haw	llm-coached + plugins	Bajo recurso, requieren aplicación de terminología

Paso 2: Configurar por par

champollion.config.json

{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "defaultMethod": "google-translate",
  "model": "google/gemini-3.5-flash",
  "languages": {
    "ja": { "name": "Japanese", "register": "Polite/formal" },
    "ko": { "name": "Korean", "register": "Formal" },
    "zh": { "name": "Simplified Chinese", "register": "Neutral" },
    "de": { "name": "German", "register": "Formal (Sie)" },
    "pt": { "name": "Brazilian Portuguese", "register": "Informal" },
    "crk": { "name": "Plains Cree (SRO)", "register": "Neutral" }
  },
  "pairs": {
    "en:ja": { "method": "llm", "model": "openai/gpt-4o" },
    "en:ko": { "method": "llm", "model": "openai/gpt-4o" },
    "en:zh": { "method": "llm", "model": "openai/gpt-4o" },
    "en:de": { "method": "llm", "model": "openai/gpt-4o" },
    "en:pt": { "method": "llm", "model": "openai/gpt-4o" },
    "en:crk": { "methodPlugin": "crk-coached-v1" }
  }
}

Nota: Los idiomas no listados en pairs heredan defaultMethod: "google-translate". No necesita listar los 30.

información

El soporte para crk está en desarrollo — consulte Soportar un idioma de bajo recurso para el estado y directrices de contribución.

Paso 3: Configurar claves de API

Necesitará ambas claves de API para esta configuración:

export OPENROUTER_API_KEY="sk-or-v1-..."
export GOOGLE_TRANSLATE_API_KEY="AIza..."

Paso 4: Ejecución de prueba primero

Siempre obtenga una vista previa antes de traducir 30 idiomas:

npx champollion sync --dry

Revise la salida. Mostrará:

• Qué pares usan qué método
• Cuántas claves son nuevas/cambiadas por local
• Llamadas de API estimadas por nivel

Paso 5: Ejecutar la sincronización

npx champollion sync

Champollion procesa cada par de forma independiente. Los pares de Nivel 2 que usan Google Translate serán rápidos. Los pares de LLM de Nivel 1 serán más lentos pero de mayor calidad. Los pares entrenados de Nivel 3 usan los datos de entrenamiento del plugin.

Actualizaciones incrementales

Después de la sincronización inicial, las ejecuciones posteriores solo traducen claves cambiadas o nuevas:

# Only keys that changed since last sync
npx champollion sync

El archivo de bloqueo (.champollion.lock) rastrea lo que se ha traducido, por lo que nunca retraduce contenido estable.

Paso 6: Auditar la calidad

Verifique el estado de todos los pares de idiomas:

npx champollion status

Esto genera una tabla que muestra el método, modelo, nivel de calidad de cada par, y si hay datos de entrenamiento o puntuaciones de referencia disponibles.

¿La salida respetó sus registros?

En el Paso 2 declaró un registro por idioma — "Polite/formal" para japonés, "Formal (Sie)" para alemán. (¿Nuevo en el término? El glosario lo explica en lenguaje simple.) Esas instrucciones van en el indicador de traducción, pero un indicador es una solicitud, no una garantía.

El arnés MT Eval Arena — la misma herramienta que impulsa la tabla de clasificación pública — puede medir la adherencia de registro y estilo en una muestra de sus traducciones. Sus métricas de estilo de escritura verifican cada salida contra el registro esperado (marcadores formales/informales, pronombres T–V, contracciones, desviación de longitud de oración) e informan un style_consistency_rate en toda la ejecución. También puede apuntarlo a un perfil de voz de marca personalizado con --style-profile.

# install the harness, then run your sample corpus through it
curl -fsSL champollion.dev/harness | bash
mt-eval run --corpus my-sample.json --style-profile brand-voice.json

Dos advertencias honestas: estas métricas son informativas (nunca entran en la puntuación compuesta de la tabla de clasificación), y la detección de formalidad se basa en marcadores — un detector de desviación, no un juicio humano. Detalles y definiciones de métricas: Métricas de estilo de escritura y registro.

Paso 7: Integración de CI

Agregue a su flujo de trabajo de GitHub Actions para que las traducciones se mantengan actuales en cada inserción:

.github/workflows/i18n-sync.yml

name: Sync Translations
on:
  push:
    paths:
      - 'locales/en/**'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Sync translations
        run: npx champollion sync
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          GOOGLE_TRANSLATE_API_KEY: ${{ secrets.GOOGLE_TRANSLATE_API_KEY }}

      - name: Commit updated translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add locales/
          git diff --staged --quiet || git commit -m "chore(i18n): sync translations"
          git push

Estimación de costos

Para un proyecto con 500 claves de origen en 30 idiomas:

Nivel	Idiomas	Método	Costo aproximado
Nivel 1 (5 idiomas)	ja, ko, zh, de, pt	GPT-4o	~$2.50/sincronización completa
Nivel 2 (18 idiomas)	it, nl, pl, etc.	Google Translate	~$0.90/sincronización completa
Nivel 3 (4 idiomas)	crk, oj, mi, haw	GPT-4o-mini entrenado	~$0.40/sincronización completa
Total	30 idiomas	Mixto	~$3.80/sincronización completa

Las sincronizaciones incrementales (5–20 claves cambiadas) cuestan una fracción de una sincronización completa.

Véase también

• Métodos de traducción — Cómo funciona cada método de traducción y cuándo usarlo
• Especificación de plugin — Cree datos de entrenamiento para cualquiera de sus idiomas de Nivel 3
• Guía de CI/CD — Patrones avanzados de CI incluyendo compilaciones de vista previa de PR
• Puerta de calidad — Cómo Champollion valida cada traducción antes de escribirla
• Idiomas soportados — Lista completa de códigos de idioma y compatibilidad de métodos
• Métricas de estilo de escritura y registro — Mida la adherencia de registro/estilo con el arnés de evaluación (métricas informativas)
• Glosario: registro — Qué significa "registro", en lenguaje simple
• Soportar un idioma de bajo recurso — Agregue datos de entrenamiento para idiomas sin cobertura de MT amplia