Naar hoofdinhoud gaan

Configuratie

Champollion werkt zonder configuratie — het detecteert automatisch localebestanden, indeling en doeltalen vanuit uw project. Voor meer controle maakt u champollion.config.json aan in de hoofdmap van uw project, of voert u het volgende uit:

npx champollion init

Volledige configuratiereferentie​

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 is nog niet geïmplementeerd Het typegen configuratieblok wordt herkend en bewaard door de configuratielader, maar het genereren van TypeScript-typen is nog niet geïmplementeerd. Dit is een tijdelijke aanduiding voor een geplande functie. Het instellen van deze waarden heeft geen effect. :::

Velden​

VeldTypeStandaardBeschrijving
versionnumber3Versie van het configuratieschema. Altijd 3.
inputLocalestring"en"Brontalcode (BCP 47).
localesDirstring"./locales"Pad naar localebestanden. Champollion scant deze map.
contentDirstringnullHugo-inhoudsmap. Schakelt vertaling van Markdown-inhoud in.
translatableFieldsstring[]nullOverschrijf de standaard vertaalbare frontmatter-velden voor inhoudsvertaling. null gebruikt ingebouwde standaardwaarden (title, description, summary).
formatstring"auto"Bestandsindeling: json, toml, yaml, of auto (detecteren op basis van extensie).
modelstring"google/gemini-3.5-flash"Standaardmodel voor LLM-methoden. Accepteert volledige OpenRouter-slugs (provider/model) of korte aliassen uit shared/model-aliases.json (bijv. gemini-flash). Directe providers gebruiken kale namen (bijv. gpt-4o).
temperaturenumber0.3LLM-temperatuur (0,0–2,0). Lager = meer deterministisch.
defaultMethodstring"llm"Standaard vertaalmethode: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api. Overschreven door de --method CLI-vlag.
batchSizenumber80Sleutels per vertaalbatch. Hoger = minder API-aanroepen, maar grotere prompts.
coachingFilestringnullPad naar een vrije-tekst coaching-promptbestand (relatief ten opzichte van de projecthoofdmap). De inhoud wordt bij het opstarten gelezen en als een Coaching guidance:-blok in de systeemprompt ingevoegd.
promptContextstringnullToepassingscontextreeks die in de systeemprompt wordt ingevoegd (bijv. "Productbeschrijvingen voor e-commerce"). Helpt het model vertalingen af te stemmen op uw domein.
jsonConcurrencynumber200Maximaal aantal parallelle localevertaling voor JSON-sleutelsynchronisatie. Overschreven door de --json-concurrency CLI-vlag.
contentConcurrencynumber48Maximaal aantal parallelle API-aanroepen voor inhoudsvertaling (Markdown/MDX). Overschreven door de --content-concurrency CLI-vlag.
fallbackPrefixstring"[EN] "Markeringsprefix die door audit en verify wordt gebruikt om verouderde onvertaalde waarden uit eerdere uitvoeringen te detecteren. Champollion schrijft dit prefix niet — het leest het alleen voor detectie.
apiKeyEnvVarstring"OPENROUTER_API_KEY"Naam van de omgevingsvariabele voor de API-sleutel. Overschrijven voor aangepaste namen van omgevingsvariabelen.
baseUrlstring""Basis-URL voor het genereren van SEO-artefacten (hreflang, sitemaps, JSON-LD).
pairsobject{}Methode-, model- en kwaliteitsoverschrijvingen per paar. Zie Paarconfiguratie.
languagesobject{}Overschrijvingen per taal. Zie Taalconfiguratie.
lint.srcDirstringnullBronmap voor lint-scanning. null = automatisch detecteren op basis van framework.
lint.ignorestring[]["node_modules", ...]Globpatronen om uit te sluiten van lint.
lint.minLengthnumber2Minimale tekenreekslengte om als hardgecodeerd te markeren.
seo.urlPatternstring"/:locale/:path"URL-patroonsjabloon voor het genereren van hreflang-tags.
seo.pagesstring[]nullExpliciete paginalijst voor SEO. null = automatisch detecteren op basis van localesleutels.
typegen.outputstringnullUitvoerpad voor gegenereerde TypeScript-typen. null = uitgeschakeld.
typegen.autoGeneratebooleanfalseTypen automatisch opnieuw genereren na elke synchronisatie.

Paarconfiguratie​

Elk bron→doelpaar kan onafhankelijk worden geconfigureerd:

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

Paarvelden​

VeldTypeBeschrijving
methodstringVertaalmethode: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api
methodPluginstringNaam van een geïnstalleerde plugin (uit .champollion/methods/)
modelstringOverschrijf het standaardmodel voor dit paar
temperaturenumberOverschrijf de standaardtemperatuur voor dit paar
batchSizenumberOverschrijf de standaard batchgrootte voor dit paar
registerstringRegister-/toonoverride (vooringestelde sleutel of vrije tekst)
endpointstringURL van het externe API-eindpunt. Vereist wanneer method api is.
coachingFilestringPad naar een coaching-promptbestand voor dit paar
promptContextstringToepassingscontext voor dit paar
qualityTierstringWeergaveniveau: standard, high, research, verified

Taalconfiguratie​

Talen accepteren drie indelingen:

Array van codes (eenvoudigst)​

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

Elke taal krijgt zijn standaardregister uit de ingebouwde registertabel. Talen zonder standaard krijgen "Professional register.".

Object met registerreeksen​

De waarde kan een vooringestelde sleutel uit de taalkaart zijn, of aangepaste registertekst:

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

Champollion controleert of de reeks overeenkomt met een vooringestelde sleutel in de taalkaart. Als dat het geval is, wordt de volledige registerprompt uit de kaart gebruikt. Als dat niet het geval is, wordt de reeks ongewijzigd gebruikt. Zie Ondersteunde talen voor beschikbare voorinstellingen.

Object met volledige configuratie​

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

U kunt verkorte notaties en volledige objecten door elkaar gebruiken in hetzelfde blok.

Taalvelden​

VeldTypeBeschrijving
registerstringStijl-/tooninstructies. Kan een vooringestelde sleutel zijn (bijv. casual-tu, formal-hapsyo) of aangepaste tekst. Zie Taalkaarten.
namestringLeesbare taalnaam (voor statusweergave)
modelstringOverschrijf het standaardmodel
temperaturenumberOverschrijf de standaardtemperatuur
batchSizenumberOverschrijf de standaard batchgrootte
coachingFilestringPad naar een coaching-promptbestand voor deze taal
promptContextstringToepassingscontext voor deze taal
maxRetriesnumberMaximaal herhalingsbudget voor mislukte batches (standaard: 3)
scriptstringISO 15924-scriptcode. Activeert scriptvalidatie in de kwaliteitspoort.

:::info Overerveringsketen Instellingen worden in deze volgorde opgelost (eerste wint):

paar-niveau → taal-niveau → globale configuratie → standaardwaarden

Als pairs["en:fr"] bijvoorbeeld model instelt, overschrijft dit zowel de model-waarden op taal- als op globaal niveau. :::

Niet-Engelse bron​

Als uw brontaal geen Engels is:

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

Vergrendelingsbestand​

Champollion maakt .champollion.lock aan om SHA-256-hashes van vertaalde bronwaarden bij te houden. Commit dit bestand zodat alle ontwikkelaars dezelfde vertaalbasis delen.

Wanneer een bronwaarde verandert, komt de hash niet meer overeen en vertaalt Champollion die sleutel opnieuw bij de volgende synchronisatie.

.champollionignore​

Maak .champollionignore aan in de hoofdmap van uw project om bestanden uit te sluiten van lint-scanning. Gebruikt globpatronen, zoals .gitignore:

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

.champollion/-map​

Champollion maakt een .champollion/-map aan in de hoofdmap van uw project voor interne status. U dient dit over het algemeen toe te voegen aan .gitignore — het is lokale optimalisatie, geen projectbron:

.champollion/
BestandDoelCommitten?
tm.jsonCache voor vertaalgeheugen — slaat eerdere vertalingen op, geïndexeerd op brontekst + locale + methodeNee (lokale cache)
xliff/*.xliffXLIFF-exportbestanden voor beoordeling door professionele vertalersNee (tijdelijk)
methods/Manifesten van geïnstalleerde methode-pluginsJa (gedeelde configuratie)
backups/Back-ups vóór omloop (aangemaakt door wrap --undo)Nee (veiligheidsnet)

Zie Vertaalgeheugen voor meer informatie over tm.json en hoe het API-kosten bespaart.

Programmatische API​

Voor bouwscripts en aangepaste integraties importeert u rechtstreeks vanuit het pakket:

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

Beschikbare exports​

ExportFunctie
TranslationMethodBasisklasse voor alle methoden
LLMMethodBasisklasse voor LLM-methoden (OpenRouter)
DirectLLMMethodBasisklasse voor directe LLM-providers (OpenAI, Anthropic, Gemini)
OpenAIMethod, AnthropicMethod, GeminiMethodDirecte LLM-providerklassen
DeepLMethod, MicrosoftTranslatorMethod, LibreTranslateMethodTraditionele MT-klassen
GoogleTranslateMethodGoogle Cloud Translation
LLMCoachedMethodCoached LLM (OpenRouter + coachinggegevens)
APIMethodExterne API-client
runSync, runContentSyncVolledige synchronisatiepijplijn
resolveConfig, resolvePairsConfiguratieresolutie
validateTranslationsKwaliteitspoort
loadCoachingData, findDictionaryMatchesCoaching-hulpprogramma's

Uitbreiding met aangepaste provider​

Breid DirectLLMMethod uit om een nieuwe LLM-provider toe te voegen in ~40 regels:

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

U krijgt vertaling, coaching, herhalingslussen, modelvalidatie, kwaliteitsniveaus en installatiehulp gratis meegeleverd. Alleen de vorm van het HTTP-verzoek is providerspecifiek. Voor niet-LLM-adapters die gebruikmaken van ruwe fetch(), gebruikt u de gedeelde fetchWithRetry()-helper uit lib/methods/fetch-with-retry.js in plaats van uw eigen herhalingslus te schrijven.

Zie ook​