Lumaktaw sa pangunahing nilalaman

Configuration

Gumagana ang Champollion nang zero-config — awtomatiko nitong nade-detect ang mga locale file, format, at target language mula sa inyong proyekto. Para sa mas maraming kontrol, gumawa ng champollion.config.json sa root ng inyong proyekto, o patakbuhin ang:

npx champollion init

Kumpletong Sanggunian ng Config​

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 Hindi pa naipapatupad ang typegen Kinikilala at pinananatili ng config loader ang typegen config block, ngunit hindi pa naipapatupad ang TypeScript type generation. Placeholder ito para sa planong feature. Walang epekto ang pag-set ng mga value na ito. :::

Mga Field​

FieldTypeDefaultDescription
versionnumber3Bersyon ng config schema. Palaging 3.
inputLocalestring"en"Source language code (BCP 47).
localesDirstring"./locales"Path papunta sa mga locale file. Ini-scan ng Champollion ang directory na ito.
contentDirstringnullHugo content directory. Pinapagana ang pagsasalin ng Markdown body.
translatableFieldsstring[]nullI-override ang mga default na translatable frontmatter field para sa pagsasalin ng content. Gumagamit ang null ng mga built-in default (title, description, summary).
formatstring"auto"File format: json, toml, yaml, o auto (i-detect mula sa extension).
modelstring"google/gemini-3.5-flash"Default na model para sa mga LLM method. Tumatanggap ng buong OpenRouter slugs (provider/model) o maiikling alias mula sa shared/model-aliases.json (hal., gemini-flash). Gumagamit ang mga direct provider ng bare names (hal., gpt-4o).
temperaturenumber0.3LLM temperature (0.0–2.0). Mas mababa = mas deterministic.
defaultMethodstring"llm"Default na method ng pagsasalin: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api. Nao-override ng --method CLI flag.
batchSizenumber80Mga key bawat translation batch. Mas mataas = mas kaunting API call, ngunit mas malalaking prompt.
coachingFilestringnullPath papunta sa free-text coaching prompt file (relative sa project root). Binabasa ang mga nilalaman sa startup at ini-inject sa system prompt bilang isang Coaching guidance: block.
promptContextstringnullApplication context string na ini-inject sa system prompt (hal., "E-commerce product descriptions"). Tumutulong ito sa model na iangkop ang mga salin sa inyong domain.
jsonConcurrencynumber200Pinakamataas na parallel locale translations para sa JSON key sync. Nao-override ng --json-concurrency CLI flag.
contentConcurrencynumber48Pinakamataas na parallel API calls para sa pagsasalin ng content (Markdown/MDX). Nao-override ng --content-concurrency CLI flag.
fallbackPrefixstring"[EN] "Marker prefix na ginagamit ng audit at verify para ma-detect ang mga legacy untranslated value mula sa mga naunang run. Hindi isinusulat ng Champollion ang prefix na ito — binabasa lamang ito para sa detection.
apiKeyEnvVarstring"OPENROUTER_API_KEY"Pangalan ng environment variable para sa API key. I-override para sa mga custom na pangalan ng env var.
baseUrlstring""Base URL para sa SEO artifact generation (hreflang, sitemaps, JSON-LD).
pairsobject{}Mga per-pair override para sa method, model, at quality. Tingnan ang Pair Configuration.
languagesobject{}Mga per-language override. Tingnan ang Language Configuration.
lint.srcDirstringnullSource directory para sa lint scanning. null = auto-detect mula sa framework.
lint.ignorestring[]["node_modules", ...]Mga glob pattern na ie-exclude mula sa lint.
lint.minLengthnumber2Minimum na haba ng string para i-flag bilang hardcoded.
seo.urlPatternstring"/:locale/:path"Template ng URL pattern para sa hreflang tag generation.
seo.pagesstring[]nullExplicit na listahan ng page para sa SEO. null = auto-detect mula sa mga locale key.
typegen.outputstringnullOutput path para sa generated TypeScript types. null = disabled.
typegen.autoGeneratebooleanfalseAwtomatikong i-regenerate ang types pagkatapos ng bawat sync.

Pair Configuration​

Maaaring i-configure nang hiwalay ang bawat source→target pair:

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

Mga Pair Field​

FieldTypeDescription
methodstringMethod ng pagsasalin: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api
methodPluginstringPangalan ng naka-install na plugin (mula sa .champollion/methods/)
modelstringI-override ang default na model para sa pair na ito
temperaturenumberI-override ang default na temperature para sa pair na ito
batchSizenumberI-override ang default na batch size para sa pair na ito
registerstringOverride para sa register/tone (preset key o freeform text)
endpointstringURL ng remote API endpoint. Kinakailangan kapag ang method ay api.
coachingFilestringPath papunta sa coaching prompt file para sa pair na ito
promptContextstringApplication context para sa pair na ito
qualityTierstringDisplay tier: standard, high, research, verified

Language Configuration​

Tumatanggap ang mga wika ng tatlong format:

Array ng mga code (pinakasimple)​

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

Nakukuha ng bawat wika ang default register nito mula sa built-in register table. Ang mga wikang walang default ay nakakakuha ng "Professional register.".

Object na may mga register string​

Maaaring ang value ay isang preset key mula sa card ng wika, o custom na register text:

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

Tinitingnan ng Champollion kung tumutugma ang string sa isang preset key sa language card. Kung oo, gagamitin ang buong register prompt mula sa card. Kung hindi, gagamitin ang string nang as-is. Tingnan ang Mga Sinusuportahang Wika para sa mga available na preset.

Object na may buong config​

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

Maaari ninyong pagsamahin ang shorthand at full objects sa iisang block.

Mga Language Field​

FieldTypeDescription
registerstringMga tagubilin sa style/tone. Maaaring isang preset key (hal., casual-tu, formal-hapsyo) o custom text. Tingnan ang Language Cards.
namestringPangalan ng wika na nababasa ng tao (para sa status display)
modelstringI-override ang default na model
temperaturenumberI-override ang default na temperature
batchSizenumberI-override ang default na batch size
coachingFilestringPath papunta sa coaching prompt file para sa wikang ito
promptContextstringApplication context para sa wikang ito
maxRetriesnumberPinakamataas na retry budget para sa mga nabigong batch (default: 3)
scriptstringISO 15924 script code. Nagtitrigger ng script validation sa quality gate.

:::info Chain ng inheritance Nare-resolve ang mga setting sa ganitong pagkakasunod-sunod (nauuna ang mananaig):

pair-level → language-level → global config → defaults

Halimbawa, kung nagse-set ang pairs["en:fr"] ng model, ino-override nito ang parehong language-level at global na mga value ng model. :::

Hindi-English na Source​

Kung hindi English ang inyong source language:

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

Lock File​

Gumagawa ang Champollion ng .champollion.lock para i-track ang mga SHA-256 hash ng mga naisaling source value. I-commit ang file na ito upang pare-pareho ang translation baseline ng lahat ng developer.

Kapag nagbago ang isang source value, hindi na tumutugma ang hash, at muling isasalin ng champollion ang key na iyon sa susunod na sync.

.champollionignore​

Gumawa ng .champollionignore sa root ng inyong proyekto upang ie-exclude ang mga file mula sa lint scanning. Gumagamit ito ng mga glob pattern, tulad ng .gitignore:

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

Directory na .champollion/​

Gumagawa ang Champollion ng directory na .champollion/ sa root ng inyong proyekto para sa internal state. Sa pangkalahatan, dapat ninyo itong idagdag sa .gitignore — lokal na optimization ito, hindi project source:

.champollion/
FilePurposeCommit?
tm.jsonTranslation Memory cache — nag-iimbak ng mga naunang salin na naka-key sa source text + locale + methodHindi (lokal na cache)
xliff/*.xliffMga XLIFF export file para sa review ng propesyonal na tagasalinHindi (transient)
methods/Mga manifest ng naka-install na method pluginOo (shared config)
backups/Mga pre-wrap backup (ginawa ng wrap --undo)Hindi (safety net)

Tingnan ang Translation Memory para sa mga detalye tungkol sa tm.json at kung paano nito natitipid ang gastos sa API.

Programmatic API​

Para sa mga build script at custom integration, direktang mag-import mula sa package:

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

Mga Available na Export​

ExportWhat It Does
TranslationMethodBase class para sa lahat ng method
LLMMethodBase class para sa mga LLM method (OpenRouter)
DirectLLMMethodBase class para sa mga direct LLM provider (OpenAI, Anthropic, Gemini)
OpenAIMethod, AnthropicMethod, GeminiMethodMga direct LLM provider class
DeepLMethod, MicrosoftTranslatorMethod, LibreTranslateMethodMga tradisyonal na MT class
GoogleTranslateMethodGoogle Cloud Translation
LLMCoachedMethodCoached LLM (OpenRouter + coaching data)
APIMethodRemote API client
runSync, runContentSyncBuong sync pipeline
resolveConfig, resolvePairsConfig resolution
validateTranslationsQuality gate
loadCoachingData, findDictionaryMatchesMga coaching utility

Custom Provider Extension​

I-extend ang DirectLLMMethod para magdagdag ng bagong LLM provider sa ~40 linya:

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

Makakakuha kayo ng translate, coaching, retry loops, model validation, quality tiers, at setup help nang libre. Tanging ang HTTP request shape lamang ang provider-specific. Para sa mga non-LLM adapter na gumagamit ng raw fetch(), gamitin ang shared na fetchWithRetry() helper mula sa lib/methods/fetch-with-retry.js sa halip na magsulat ng sarili ninyong retry loop.

Tingnan Din​