Ir para o conteúdo principal

Configuração

Champollion funciona sem configuração — ele detecta automaticamente arquivos de locale, formato e idiomas de destino do seu projeto. Para mais controle, crie champollion.config.json na raiz do seu projeto, ou execute:

npx champollion init

Referência Completa de Configuração​

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 ainda não foi implementado O bloco de configuração typegen é reconhecido e preservado pelo carregador de configuração, mas a geração de tipos TypeScript ainda não foi implementada. Este é um espaço reservado para um recurso planejado. Definir esses valores não tem efeito. :::

Campos​

CampoTipoPadrãoDescrição
versionnumber3Versão do schema de configuração. Sempre 3.
inputLocalestring"en"Código do idioma de origem (BCP 47).
localesDirstring"./locales"Caminho para arquivos de locale. Champollion escaneia este diretório.
contentDirstringnullDiretório de conteúdo Hugo. Habilita tradução de corpo Markdown.
translatableFieldsstring[]nullSobrescreve campos de frontmatter traduzíveis padrão para tradução de conteúdo. null usa padrões integrados (title, description, summary).
formatstring"auto"Formato de arquivo: json, toml, yaml, ou auto (detectar pela extensão).
modelstring"google/gemini-3.5-flash"Modelo padrão para métodos LLM. Aceita slugs completos do OpenRouter (provider/model) ou aliases curtos de shared/model-aliases.json (ex: gemini-flash). Provedores diretos usam nomes simples (ex: gpt-4o).
temperaturenumber0.3Temperatura do LLM (0.0–2.0). Menor = mais determinístico.
defaultMethodstring"llm"Método de tradução padrão: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api. Sobrescrito pela flag CLI --method.
batchSizenumber80Chaves por lote de tradução. Maior = menos chamadas de API, mas prompts maiores.
coachingFilestringnullCaminho para arquivo de prompt de coaching em texto livre (relativo à raiz do projeto). O conteúdo é lido na inicialização e injetado no prompt do sistema como um bloco Coaching guidance:.
promptContextstringnullString de contexto da aplicação injetada no prompt do sistema (ex: "Descrições de produtos de e-commerce"). Ajuda o modelo a adaptar traduções ao seu domínio.
jsonConcurrencynumber200Máximo de traduções de locale paralelas para sincronização de chaves JSON. Sobrescrito pela flag CLI --json-concurrency.
contentConcurrencynumber48Máximo de chamadas de API paralelas para tradução de conteúdo (Markdown/MDX). Sobrescrito pela flag CLI --content-concurrency.
fallbackPrefixstring"[EN] "Prefixo de marcador usado por audit e verify para detectar valores não traduzidos legados de execuções anteriores. Champollion não escreve este prefixo — apenas o lê para detecção.
apiKeyEnvVarstring"OPENROUTER_API_KEY"Nome da variável de ambiente para a chave de API. Sobrescreva para nomes de variáveis de ambiente personalizadas.
baseUrlstring""URL base para geração de artefatos SEO (hreflang, sitemaps, JSON-LD).
pairsobject{}Sobrescritas de método, modelo e qualidade por par. Veja Configuração de Par.
languagesobject{}Sobrescritas por idioma. Veja Configuração de Idioma.
lint.srcDirstringnullDiretório de origem para escaneamento de lint. null = detectar automaticamente do framework.
lint.ignorestring[]["node_modules", ...]Padrões glob para excluir do lint.
lint.minLengthnumber2Comprimento mínimo de string para sinalizar como hardcoded.
seo.urlPatternstring"/:locale/:path"Padrão de template de URL para geração de tag hreflang.
seo.pagesstring[]nullLista explícita de páginas para SEO. null = detectar automaticamente das chaves de locale.
typegen.outputstringnullCaminho de saída para tipos TypeScript gerados. null = desabilitado.
typegen.autoGeneratebooleanfalseRegenerar tipos automaticamente após cada sincronização.

Configuração de Par​

Cada par origem→destino pode ser configurado independentemente:

{
  "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 Par​

CampoTipoDescrição
methodstringMétodo de tradução: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api
methodPluginstringNome de um plugin instalado (de .champollion/methods/)
modelstringSobrescreva o modelo padrão para este par
temperaturenumberSobrescreva a temperatura padrão para este par
batchSizenumberSobrescreva o tamanho de lote padrão para este par
registerstringSobrescrita de registro/tom (chave de preset ou texto livre)
endpointstringURL de endpoint de API remota. Obrigatório quando method é api.
coachingFilestringCaminho para arquivo de prompt de coaching para este par
promptContextstringContexto da aplicação para este par
qualityTierstringTier de exibição: standard, high, research, verified

Configuração de Idioma​

Idiomas aceitam três formatos:

Array de códigos (mais simples)​

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

Cada idioma obtém seu registro padrão da tabela de registro integrada. Idiomas sem um padrão recebem "Professional register.".

Objeto com strings de registro​

O valor pode ser uma chave de preset do cartão do idioma, ou texto de registro personalizado:

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

Champollion verifica se a string corresponde a uma chave de preset no cartão do idioma. Se corresponder, o prompt de registro completo do cartão é usado. Se não, a string é usada como está. Veja Idiomas Suportados para presets disponíveis.

Objeto com configuração completa​

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

Você pode misturar objetos abreviados e completos no mesmo bloco.

Campos de Idioma​

CampoTipoDescrição
registerstringInstruções de estilo/tom. Pode ser uma chave de preset (ex: casual-tu, formal-hapsyo) ou texto personalizado. Veja Cartões de Idioma.
namestringNome de idioma legível por humanos (para exibição de status)
modelstringSobrescreva o modelo padrão
temperaturenumberSobrescreva a temperatura padrão
batchSizenumberSobrescreva o tamanho de lote padrão
coachingFilestringCaminho para arquivo de prompt de coaching para este idioma
promptContextstringContexto da aplicação para este idioma
maxRetriesnumberOrçamento máximo de tentativas para lotes falhados (padrão: 3)
scriptstringCódigo de script ISO 15924. Dispara validação de script no portão de qualidade.

:::info Cadeia de herança As configurações são resolvidas nesta ordem (primeira vence):

nível de par → nível de idioma → configuração global → padrões

Por exemplo, se pairs["en:fr"] define model, ele sobrescreve os valores model de nível de idioma e global. :::

Origem Não-Inglesa​

Se seu idioma de origem não for inglês:

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

Arquivo de Lock​

Champollion cria .champollion.lock para rastrear hashes SHA-256 de valores de origem traduzidos. Faça commit deste arquivo para que todos os desenvolvedores compartilhem a mesma linha de base de tradução.

Quando um valor de origem muda, o hash não corresponde mais, e champollion retraduz essa chave na próxima sincronização.

.champollionignore​

Crie .champollionignore na raiz do seu projeto para excluir arquivos do escaneamento lint. Usa padrões glob, como .gitignore:

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

Diretório .champollion/​

Champollion cria um diretório .champollion/ na raiz do seu projeto para estado interno. Você geralmente deve adicionar isto a .gitignore — é otimização local, não fonte do projeto:

.champollion/
ArquivoPropósitoFazer Commit?
tm.jsonCache de Memória de Tradução — armazena traduções anteriores indexadas por texto de origem + locale + métodoNão (cache local)
xliff/*.xliffArquivos de exportação XLIFF para revisão de tradutor profissionalNão (transitório)
methods/Manifestos de plugin de método instaladoSim (configuração compartilhada)
backups/Backups pré-wrap (criados por wrap --undo)Não (rede de segurança)

Veja Memória de Tradução para detalhes sobre tm.json e como economiza custos de API.

API Programática​

Para scripts de build e integrações personalizadas, importe diretamente do pacote:

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' }

Exportações Disponíveis​

ExportaçãoO Que Faz
TranslationMethodClasse base para todos os métodos
LLMMethodClasse base para métodos LLM (OpenRouter)
DirectLLMMethodClasse base para provedores LLM diretos (OpenAI, Anthropic, Gemini)
OpenAIMethod, AnthropicMethod, GeminiMethodClasses de provedor LLM direto
DeepLMethod, MicrosoftTranslatorMethod, LibreTranslateMethodClasses de MT tradicional
GoogleTranslateMethodGoogle Cloud Translation
LLMCoachedMethodLLM com Coaching (OpenRouter + dados de coaching)
APIMethodCliente de API remota
runSync, runContentSyncPipeline de sincronização completo
resolveConfig, resolvePairsResolução de configuração
validateTranslationsPortão de qualidade
loadCoachingData, findDictionaryMatchesUtilitários de coaching

Extensão de Provedor Personalizado​

Estenda DirectLLMMethod para adicionar um novo provedor LLM em ~40 linhas:

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.'];
  }
}

Você obtém tradução, coaching, loops de tentativa, validação de modelo, tiers de qualidade e ajuda de configuração gratuitamente. Apenas a forma da solicitação HTTP é específica do provedor. Para adaptadores não-LLM que usam fetch() bruto, use o helper fetchWithRetry() compartilhado de lib/methods/fetch-with-retry.js em vez de escrever seu próprio loop de tentativa.

Veja Também​