Eine benutzerdefinierte Methode als API bereitstellen

Die api-Methode von champollion ermöglicht es Ihnen, jedes Übersetzungspaar auf einen externen HTTP-Endpunkt zu verweisen. So integrieren Sie Pipelines, die für einen einzelnen LLM-Prompt zu komplex sind — morphologische Analysatoren, Finite-State-Transducer (FSTs), mehrstufige LLM-Ketten oder jede benutzerdefinierte Forschungsmethode, die Sie entwickelt haben.

Warum ein API-Dienst?

Manche Übersetzungspipelines lassen sich nicht innerhalb eines einfachen Anfrage-Antwort-Zyklus ausführen:

Pipeline-Schritt	Beispiel
Morphologische Zerlegung	Polysynthetische Wörter vor der Übersetzung in Morpheme aufteilen
FST-Validierung	Ausgaben ablehnen, die phonologische oder morphologische Regeln verletzen
Mehrstufige LLM-Ketten	Generieren → Verifizieren → Korrigieren-Zyklen mit verschiedenen Modellen
Wörterbuch-Abfrage	Während der Pipeline einen kuratierten zweisprachigen Wörterbuchabgleich durchführen
Human-in-the-Loop	Unsichere Übersetzungen zur Expertenprüfung in eine Warteschlange stellen

Die api-Methode behandelt Ihre Pipeline als Blackbox — champollion sendet Quellzeichenketten, Ihr Dienst gibt Übersetzungen zurück. Was im Inneren geschieht, liegt vollständig bei Ihnen.

Architektur

Einrichtung Ihres Dienstes

Ihr API-Dienst muss einen einzigen Endpunkt implementieren, der JSON akzeptiert und zurückgibt:

Anfrageformat

champollion sendet exakt diesen JSON-Body (siehe api.js):

POST /translate
Content-Type: application/json
Authorization: Bearer <CHAMPOLLION_API_KEY>

{
  "source_locale": "en",
  "target_locale": "crk",
  "method": "crk-coached-v1",
  "keys": {
    "greeting": "Hello, welcome to our app",
    "farewell": "Goodbye and thanks"
  }
}

Feld	Typ	Beschreibung
`source_locale`	string	BCP-47-Quellsprachcode
`target_locale`	string	BCP-47-Zielsprachcode
`method`	string	Plugin-Name oder `"default"`
`keys`	object	Zuordnung von Schlüssel → zu übersetzende Quellzeichenkette

### Response Format

Your service must return a `translations` object. An optional `meta` object can include cost and diagnostic info:

```json
{
  "translations": {
    "greeting": "tânisi, pê-kîwêw ôta",
    "farewell": "ekosi mâka, kinanâskomitin"
  },
  "meta": {
    "model": "my-custom-pipeline/v1",
    "cost_usd": 0.0042,
    "method": "decompose-translate-validate"
  }
}

Field	Type	Required	Description
`translations`	object	✅	Map of key → translated string
`meta`	object	—	Optional metadata
`meta.cost_usd`	number	—	If present, displayed in champollion's output
`errors`	object	—	For partial success (HTTP 207): map of key → `{ message }`

Minimal Express Server

import express from 'express';

const app = express();
app.use(express.json());

/**
 * champollion API contract:
 *
 * Request:  { source_locale, target_locale, method, keys: { "key": "source" } }
 * Response: { translations: { "key": "translated" }, meta: { ... } }
 */
app.post('/translate', async (req, res) => {
  const { source_locale, target_locale, method, keys } = req.body;

  const translations = {};

  for (const [key, source] of Object.entries(keys)) {
    // --- Your pipeline goes here ---
    // Step 1: Morphological decomposition
    const morphemes = await decompose(source, source_locale);

    // Step 2: LLM translation with context
    const draft = await llmTranslate(morphemes, target_locale);

    // Step 3: FST validation
    const validated = await fstValidate(draft, target_locale);

    // Step 4: Post-processing (orthography normalization, etc.)
    translations[key] = await postProcess(validated);
  }

  res.json({
    translations,
    meta: {
      model: 'my-custom-pipeline/v1',
      method: 'decompose-translate-validate',
    },
  });
});

app.listen(3001, () => {
  console.log('Translation API running on http://localhost:3001');
});

Configuring champollion

Point a translation pair at your running service in champollion.config.json:

{
  "inputLocale": "en",
  "pairs": {
    "en:crk": {
      "method": "api",
      "endpoint": "http://localhost:3001/translate",
      "register": "Formal Plains Cree. Use SRO orthography."
    }
  }
}

Then run sync as usual:

npx champollion sync

champollion will POST your source strings to the endpoint and write the returned translations to crk.json.

Case Study: Plains Cree Pipeline

:::info Under Development The Plains Cree pipeline described below is under active development and is not yet running in production. Details here reflect the current design direction and may change as the project evolves. :::

The arena project demonstrates this pattern. Its Plains Cree pipeline uses:

Morphological decomposition — Break polysynthetic Cree words into translatable morpheme chains
LLM translation — Context-enriched GPT-4o translation with coaching data (SRO orthography rules, register instructions)
FST validation — Finite-state transducer checks that outputs conform to Cree phonological rules
Confidence scoring — Each translation gets a confidence score based on FST pass rate and dictionary coverage

The entire pipeline runs as a single HTTP endpoint that champollion calls via the api method.

Running Evaluations

After translating, you can evaluate output quality using the harness directly:

# Clone the harness
git clone https://github.com/gamedaysuits/arena.git
cd arena
pip install -e .

# Run the evaluation against your method's output
mt-eval run --corpus data/edtekla-dev-v1.json --submit

This produces structured evaluation records with chrF++, BLEU, and exact match scores that can be used as regression baselines.

Authentication

If your API requires authentication, set the apiKey field or use an environment variable:

{
  "pairs": {
    "en:crk": {
      "method": "api",
      "endpoint": "https://my-mt-service.example.com/translate",
      "apiKey": "${CRK_API_KEY}"
    }
  }
}

Data Sovereignty & OCAP Principles

The api method is particularly important for Indigenous language communities. By self-hosting the translation pipeline, a community keeps full control over:

Proprietary coaching data — register instructions, orthography rules, and domain glossaries never leave community infrastructure.
Linguistic resources — curated dictionaries, FST grammars, and elder-verified translations remain under community ownership.
Access policies — the community decides who can call the endpoint and under what terms.

This aligns with OCAP® principles (Ownership, Control, Access, Possession), ensuring that sensitive language data is governed by the community rather than a third-party platform.

Tipp

Combine the api method with a private deployment (e.g., a community-hosted VM or on-prem server) for the strongest data-sovereignty posture. See Support a Low-Resource Language for a full walkthrough.

Cost Estimation

The api method returns null for cost estimation by default — your service controls pricing. If you want to provide cost transparency, have your API return a cost field in the metadata:

{
  "translations": { "...": "..." },
  "metadata": {
    "cost": {
      "estimatedCost": 0.0042,
      "currency": "USD",
      "source": "my-service-pricing"
    }
  }
}

Best Practices

Geben Sie bei Fehlern leere Zeichenketten zurück — Geben Sie nicht die Quellzeichenkette als „Übersetzung“ zurück. Geben Sie "" zurück, und das Quality-Gate von champollion erkennt dies. Der Schlüssel wird übersprungen und beim nächsten Sync erneut versucht.
Fügen Sie Konfidenzwerte hinzu — Wenn Ihre Pipeline die Qualität abschätzen kann, geben Sie diese in den Metadaten zurück. Dies hilft beim Qualitätsaudit.
Implementieren Sie Health-Checks — Fügen Sie einen GET /health-Endpunkt hinzu, damit champollion die Konnektivität vor dem Start eines großen Syncs überprüfen kann.
Begrenzen Sie die Anfragerate sauber — Wenn Ihre Pipeline Durchsatzgrenzen hat, geben Sie 429-Statuscodes zurück. Das Batch-System von champollion wird daraufhin zurückfahren.
Protokollieren Sie alles — Mehrstufige Pipelines können unbemerkt fehlschlagen. Protokollieren Sie Eingabe/Ausgabe jedes Schritts zur Fehlersuche.

Lizenzierung

Das Muster der api-Methode ist vollständig offen — es gibt keine Lizenzbeschränkungen dafür, Ihre eigene Übersetzungspipeline als HTTP-Dienst zu kapseln. Das arena ist unter der MIT-Lizenz für Referenzimplementierungen verfügbar.

Siehe auch

Übersetzungsmethoden — Übersicht über jede integrierte Methode (openai, google, api usw.)
Plugin-Spezifikation — vollständiges Schema für champollion.config.json einschließlich der api-Methodenfelder
Eine ressourcenarme Sprache unterstützen — durchgängige Anleitung für unterversorgte Sprachen, einschließlich der OCAP-Prinzipien
Architektur — wie die Sync-Schleife, das Batching und der Methoden-Dispatch von champollion funktionieren
MT-Evaluierung — Evaluierungsmethodik, Metriken und der Einreichungsprozess für die Bestenliste
Methoden-Bestenliste — Live-Qualitätsrankings über Methoden und Sprachpaare hinweg

Warum ein API-Dienst?​

Architektur​

Einrichtung Ihres Dienstes​

Anfrageformat​

Minimal Express Server​

Configuring champollion​

Case Study: Plains Cree Pipeline​

Running Evaluations​

Authentication​

Data Sovereignty & OCAP Principles​

Cost Estimation​

Best Practices​

Lizenzierung​

Siehe auch​