Ir al contenido principal

Configuración

Champollion funciona sin configuración — detecta automáticamente archivos de locale, formato e idiomas de destino desde su proyecto. Para mayor control, cree champollion.config.json en la raíz de su proyecto, o ejecute:

npx champollion init

Referencia de Configuración Completa​

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "contentDir": null,
  "translatableFields": null,
  "format": "auto",
  "model": "google/gemini-3.5-flash",
  "temperature": 0.3,
  "defaultMethod": "llm",
  "batchSize": 80,
  "coachingFile": null,
  "promptContext": null,
  "jsonConcurrency": 200,
  "contentConcurrency": 48,
  "fallbackPrefix": "[EN] ",
  "apiKeyEnvVar": "OPENROUTER_API_KEY",
  "baseUrl": "",
  "pairs": {},
  "languages": {},
  "lint": {
    "srcDir": null,
    "ignore": ["node_modules", ".next", "dist"],
    "minLength": 2
  },
  "seo": {
    "urlPattern": "/:locale/:path",
    "pages": null
  },
  "typegen": {
    "output": null,
    "autoGenerate": false
  }
}

:::note typegen aún no está implementado El bloque de configuración typegen es reconocido y preservado por el cargador de configuración, pero la generación de tipos TypeScript aún no está implementada. Este es un marcador de posición para una característica planeada. Establecer estos valores no tiene efecto. :::

Campos​

CampoTipoPredeterminadoDescripción
versionnumber3Versión del esquema de configuración. Siempre 3.
inputLocalestring"en"Código de idioma de origen (BCP 47).
localesDirstring"./locales"Ruta a archivos de locale. Champollion escanea este directorio.
contentDirstringnullDirectorio de contenido Hugo. Habilita la traducción del cuerpo Markdown.
translatableFieldsstring[]nullAnula los campos de frontmatter traducibles predeterminados para la traducción de contenido. null utiliza los valores predeterminados integrados (title, description, summary).
formatstring"auto"Formato de archivo: json, toml, yaml, o auto (detectar desde la extensión).
modelstring"google/gemini-3.5-flash"Modelo predeterminado para métodos LLM. Acepta slugs completos de OpenRouter (provider/model) o alias cortos de shared/model-aliases.json (p. ej., gemini-flash). Los proveedores directos utilizan nombres simples (p. ej., gpt-4o).
temperaturenumber0.3Temperatura LLM (0.0–2.0). Menor = más determinista.
defaultMethodstring"llm"Método de traducción predeterminado: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api. Anulado por la bandera CLI --method.
batchSizenumber80Claves por lote de traducción. Mayor = menos llamadas API, pero prompts más grandes.
coachingFilestringnullRuta a un archivo de coaching de texto libre (relativa a la raíz del proyecto). El contenido se lee al inicio e inyecta en el prompt del sistema como un bloque Coaching guidance:.
promptContextstringnullCadena de contexto de aplicación inyectada en el prompt del sistema (p. ej., "Descripciones de productos de comercio electrónico"). Ayuda al modelo a adaptar las traducciones a su dominio.
jsonConcurrencynumber200Máximo de traducciones de locale paralelas para sincronización de claves JSON. Anulado por la bandera CLI --json-concurrency.
contentConcurrencynumber48Máximo de llamadas API paralelas para traducción de contenido (Markdown/MDX). Anulado por la bandera CLI --content-concurrency.
fallbackPrefixstring"[EN] "Prefijo de marcador utilizado por audit y verify para detectar valores heredados sin traducir de ejecuciones anteriores. Champollion no escribe este prefijo — solo lo lee para detección.
apiKeyEnvVarstring"OPENROUTER_API_KEY"Nombre de variable de entorno para la clave API. Anule para nombres de variables de entorno personalizadas.
baseUrlstring""URL base para generación de artefactos SEO (hreflang, sitemaps, JSON-LD).
pairsobject{}Anulaciones de método, modelo y calidad por par. Vea Configuración de Pares.
languagesobject{}Anulaciones por idioma. Vea Configuración de Idioma.
lint.srcDirstringnullDirectorio de origen para escaneo de lint. null = auto-detectar desde el framework.
lint.ignorestring[]["node_modules", ...]Patrones glob a excluir del lint.
lint.minLengthnumber2Longitud mínima de cadena para marcar como codificada.
seo.urlPatternstring"/:locale/:path"Plantilla de patrón URL para generación de etiquetas hreflang.
seo.pagesstring[]nullLista de páginas explícita para SEO. null = auto-detectar desde claves de locale.
typegen.outputstringnullRuta de salida para tipos TypeScript generados. null = deshabilitado.
typegen.autoGeneratebooleanfalseAuto-regenerar tipos después de cada sincronización.

Configuración de Pares​

Cada par origen→destino puede configurarse de forma independiente:

{
  "pairs": {
    "en:fr": {
      "method": "google-translate",
      "qualityTier": "high"
    },
    "en:ja": {
      "method": "llm",
      "model": "google/gemini-2.5-pro"
    },
    "en:crk": {
      "methodPlugin": "crk-coached-v1"
    }
  }
}

Campos de Pares​

CampoTipoDescripción
methodstringMétodo de traducción: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api
methodPluginstringNombre de un plugin instalado (de .champollion/methods/)
modelstringAnule el modelo predeterminado para este par
temperaturenumberAnule la temperatura predeterminada para este par
batchSizenumberAnule el tamaño de lote predeterminado para este par
registerstringAnulación de registro/tono (clave preestablecida o texto libre)
endpointstringURL de punto final de API remota. Requerido cuando method es api.
coachingFilestringRuta a un archivo de coaching para este par
promptContextstringContexto de aplicación para este par
qualityTierstringNivel de visualización: standard, high, research, verified

Configuración de Idioma​

Los idiomas aceptan tres formatos:

Matriz de códigos (más simple)​

{
  "languages": ["fr", "de", "ja"]
}

Cada idioma obtiene su registro predeterminado de la tabla de registro integrada. Los idiomas sin un predeterminado obtienen "Professional register.".

Objeto con cadenas de registro​

El valor puede ser una clave preestablecida de la tarjeta del idioma, o texto de registro personalizado:

{
  "languages": {
    "fr": "casual-tu",
    "ko": "formal-hapsyo",
    "ja": "Custom: Polite Japanese for a gaming app."
  }
}

Champollion verifica si la cadena coincide con una clave preestablecida en la tarjeta del idioma. Si es así, se utiliza el prompt de registro completo de la tarjeta. Si no, la cadena se utiliza tal cual. Vea Idiomas Soportados para los preestablecidos disponibles.

Objeto con configuración completa​

{
  "languages": {
    "crk": {
      "name": "Plains Cree",
      "register": "SRO syllabics with grammatical precision.",
      "model": "google/gemini-2.5-pro",
      "batchSize": 5,
      "maxRetries": 5,
      "script": "cans"
    }
  }
}

Puede mezclar objetos abreviados y completos en el mismo bloque.

Campos de Idioma​

CampoTipoDescripción
registerstringInstrucciones de estilo/tono. Puede ser una clave preestablecida (p. ej., casual-tu, formal-hapsyo) o texto personalizado. Vea Tarjetas de Idioma.
namestringNombre de idioma legible por humanos (para visualización de estado)
modelstringAnule el modelo predeterminado
temperaturenumberAnule la temperatura predeterminada
batchSizenumberAnule el tamaño de lote predeterminado
coachingFilestringRuta a un archivo de coaching para este idioma
promptContextstringContexto de aplicación para este idioma
maxRetriesnumberPresupuesto máximo de reintentos para lotes fallidos (predeterminado: 3)
scriptstringCódigo de script ISO 15924. Activa validación de script en la puerta de calidad.

:::info Cadena de herencia Los ajustes se resuelven en este orden (el primero gana):

nivel de par → nivel de idioma → configuración global → predeterminados

Por ejemplo, si pairs["en:fr"] establece model, anula tanto el nivel de idioma como los valores globales de model. :::

Origen No Inglés​

Si su idioma de origen no es inglés:

# CLI flag (one-time)
npx champollion sync --source fr
champollion.config.json (permanent)
{
  "inputLocale": "fr"
}

Archivo de Bloqueo​

Champollion crea .champollion.lock para rastrear hashes SHA-256 de valores de origen traducidos. Confirme este archivo para que todos los desarrolladores compartan la misma línea base de traducción.

Cuando un valor de origen cambia, el hash ya no coincide, y champollion retraduce esa clave en la siguiente sincronización.

.champollionignore​

Cree .champollionignore en la raíz de su proyecto para excluir archivos del escaneo de lint. Utiliza patrones glob, como .gitignore:

.champollionignore
src/components/legacy/**
src/utils/constants.js
**/*.test.js

Directorio .champollion/​

Champollion crea un directorio .champollion/ en la raíz de su proyecto para estado interno. Generalmente debe agregar esto a .gitignore — es optimización local, no fuente del proyecto:

.champollion/
ArchivoPropósito¿Confirmar?
tm.jsonCaché de Memoria de Traducción — almacena traducciones anteriores indexadas por texto de origen + locale + métodoNo (caché local)
xliff/*.xliffArchivos de exportación XLIFF para revisión de traductor profesionalNo (transitorio)
methods/Manifiestos de plugins de método instaladosSí (configuración compartida)
backups/Copias de seguridad pre-wrap (creadas por wrap --undo)No (red de seguridad)

Vea Memoria de Traducción para detalles sobre tm.json y cómo ahorra costos de API.

API Programática​

Para scripts de compilación e integraciones personalizadas, importe directamente desde el paquete:

import { GeminiMethod, runSync, resolveConfig } from 'champollion';

// Use a method class directly
const gemini = new GeminiMethod();
const result = await gemini.translate(
  ['greeting', 'farewell'],
  { greeting: 'Hello', farewell: 'Goodbye' },
  { target: 'fr', name: 'French', register: 'formal', model: 'gemini-2.5-flash' },
  { cwd: process.cwd() }
);
// result = { greeting: 'Bonjour', farewell: 'Au revoir' }

Exportaciones Disponibles​

ExportaciónQué Hace
TranslationMethodClase base para todos los métodos
LLMMethodClase base para métodos LLM (OpenRouter)
DirectLLMMethodClase base para proveedores LLM directos (OpenAI, Anthropic, Gemini)
OpenAIMethod, AnthropicMethod, GeminiMethodClases de proveedores LLM directos
DeepLMethod, MicrosoftTranslatorMethod, LibreTranslateMethodClases de MT tradicional
GoogleTranslateMethodGoogle Cloud Translation
LLMCoachedMethodLLM Coached (OpenRouter + datos de coaching)
APIMethodCliente de API remota
runSync, runContentSyncCanalización de sincronización completa
resolveConfig, resolvePairsResolución de configuración
validateTranslationsPuerta de calidad
loadCoachingData, findDictionaryMatchesUtilidades de coaching

Extensión de Proveedor Personalizado​

Extienda DirectLLMMethod para agregar un nuevo proveedor LLM en ~40 líneas:

import { DirectLLMMethod } from 'champollion';

class MistralMethod extends DirectLLMMethod {
  constructor(options) {
    super(options);
    this.name = 'mistral';
  }
  _getApiKeyEnvVar()     { return 'MISTRAL_API_KEY'; }
  _getApiKeyOptionsKey() { return 'mistralApiKey'; }
  _getDefaultModel()     { return 'mistral-large-latest'; }
  _getProviderLabel()    { return 'Mistral'; }

  _buildApiRequest({ prompt, systemMessage, apiKey, model, temperature }) {
    return {
      url: 'https://api.mistral.ai/v1/chat/completions',
      headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
      body: {
        model,
        messages: [
          ...(systemMessage ? [{ role: 'system', content: systemMessage }] : []),
          { role: 'user', content: prompt },
        ],
        temperature,
      },
    };
  }

  _extractResponseText(json) {
    return json.choices?.[0]?.message?.content;
  }

  // Optional but recommended: provider-specific setup help when translation fails
  getSetupHelp() {
    if (!process.env.MISTRAL_API_KEY) {
      return [
        '',
        '  ┌─ Missing API Key ─────────────────────────────────────────────┐',
        '  │ Mistral requires an API key from https://console.mistral.ai   │',
        '  │ Run: export MISTRAL_API_KEY=...                               │',
        '  └────────────────────────────────────────────────────────────────┘',
      ];
    }
    return ['        API key is set but translation failed. Check your Mistral dashboard.'];
  }
}

Obtiene traducción, coaching, bucles de reintento, validación de modelo, niveles de calidad y ayuda de configuración de forma gratuita. Solo la forma de solicitud HTTP es específica del proveedor. Para adaptadores que no son LLM que utilizan fetch() sin procesar, utilice el ayudante compartido fetchWithRetry() de lib/methods/fetch-with-retry.js en lugar de escribir su propio bucle de reintento.

Vea También​