الانتقال إلى المحتوى الرئيسي

تقديم طريقة مخصصة كواجهة API

تتيح لك طريقة api في champollion توجيه أي زوج ترجمة إلى نقطة نهاية HTTP خارجية. هذه هي الطريقة التي تدمج بها خطوط المعالجة (pipelines) المعقدة جدًا بحيث لا يمكن تنفيذها في موجّه LLM واحد — مثل المحلّلات الصرفية، ومحوّلات الحالات المنتهية (FSTs)، وسلاسل LLM متعددة الخطوات، أو أي طريقة بحثية مخصصة قمت ببنائها.

لماذا خدمة API؟​

بعض خطوط معالجة الترجمة لا يمكن تشغيلها ضمن دورة بسيطة من الموجّه والاستجابة:

خطوة خط المعالجةمثال
التفكيك الصرفيتقسيم الكلمات متعددة التركيب إلى مورفيمات قبل الترجمة
التحقق عبر FSTرفض المخرجات التي تنتهك القواعد الصوتية أو الصرفية
سلاسل LLM متعددة الخطواتدورات توليد ← تحقق ← تصحيح باستخدام نماذج مختلفة
البحث في القاموسالمراجعة المتقاطعة مع قاموس ثنائي اللغة منسّق أثناء المعالجة
الإنسان في حلقة المعالجةوضع الترجمات غير المؤكدة في طابور لمراجعة الخبراء

تتعامل طريقة api مع خط المعالجة الخاص بك كصندوق أسود — يرسل champollion النصوص المصدرية، وتُعيد خدمتك الترجمات. أما ما يحدث في الداخل فهو متروك لك بالكامل.

البنية المعمارية​

إعداد خدمتك​

يجب أن تنفّذ خدمة API الخاصة بك نقطة نهاية واحدة تستقبل JSON وتُعيده:

صيغة الطلب​

يرسل champollion نص JSON هذا بالضبط (انظر 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"
  }
}
الحقلالنوعالوصف
source_localestringرمز لغة المصدر وفق BCP 47
target_localestringرمز اللغة الهدف وفق BCP 47
methodstringاسم الإضافة (plugin) أو "default"
keysobjectخريطة من المفتاح ← النص المصدري المراد ترجمته

### 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"
  }
}
FieldTypeRequiredDescription
translationsobject✅Map of key → translated string
metaobject—Optional metadata
meta.cost_usdnumber—If present, displayed in champollion's output
errorsobject—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:

  1. Morphological decomposition — Break polysynthetic Cree words into translatable morpheme chains
  2. LLM translation — Context-enriched GPT-4o translation with coaching data (SRO orthography rules, register instructions)
  3. FST validation — Finite-state transducer checks that outputs conform to Cree phonological rules
  4. 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.

نصيحة

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

أفضل الممارسات​

  1. أعد سلاسل نصية فارغة عند الإخفاق — لا تُعِد النص المصدري على أنه "ترجمة". أعد "" وستلتقطه بوابة الجودة في champollion. سيتم تخطي المفتاح وإعادة المحاولة في المزامنة التالية.
  2. ضمّن درجات الثقة — إذا كان خط المعالجة لديك قادرًا على تقدير الجودة، فأعدها ضمن البيانات الوصفية. هذا يساعد في تدقيق الجودة.
  3. نفّذ فحوصات الصحة — أضف نقطة نهاية GET /health حتى يتمكن champollion من التحقق من الاتصال قبل بدء عملية مزامنة كبيرة.
  4. طبّق تحديد المعدل بسلاسة — إذا كان لخط المعالجة لديك حدود في معدل المعالجة، فأعد رموز الحالة 429. سيتراجع نظام الدفعات في champollion تلقائيًا.
  5. سجّل كل شيء — قد تفشل خطوط المعالجة متعددة الخطوات دون أي إشارة. سجّل مدخلات ومخرجات كل خطوة لأغراض تصحيح الأخطاء.

الترخيص​

نمط طريقة api مفتوح بالكامل — لا توجد أي قيود ترخيص على تغليف خط معالجة الترجمة الخاص بك كخدمة HTTP. كما أن arena متاح بموجب ترخيص MIT للتنفيذات المرجعية.

انظر أيضًا​