civjdr/API_CONFLUENT.md

API ConfluentTranslator - Documentation

Cette API permet de traduire entre le français et la langue de la Confluence (Ancien Confluent et Proto-Confluent).

URL de base

https://confluent.etheryale.com

Authentification

Toutes les requêtes (sauf /api/stats) nécessitent une authentification par clé API :

X-API-Key: [CLÉ_API]

Note : Claude Code a accès à la clé API pour ce projet. Elle n'est pas incluse dans ce document pour des raisons de sécurité.

---

Endpoints principaux

1. Traduire FR → Confluent (avec LLM)

Utilise un LLM (Claude ou GPT) pour traduire du français vers le Confluent.

Endpoint : POST /translate

Paramètres :

• text (string, requis) : Texte français à traduire
• target (string, requis) : "ancien" ou "proto"
• provider (string, requis) : "anthropic" (recommandé) ou "openai"
• model (string, requis) :
  • Anthropic : "claude-sonnet-4-20250514" ou "claude-haiku-4-20250514"
  • OpenAI : "gpt-4o" ou "gpt-4o-mini"
• temperature (number, optionnel) : Température du LLM (défaut: 1.0)
• useLexique (boolean, optionnel) : Utiliser l'analyse contextuelle (défaut: true)

Exemple :

curl -X POST https://confluent.etheryale.com/translate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: [CLÉ_API]" \
  -d '{
    "text": "bonjour",
    "target": "ancien",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }'

Réponse :

{
  "layer1": {
    "translation": "oratosa"
  },
  "layer2": {
    "wordsFound": [...],
    "wordsNotFound": [...],
    "entriesUsed": 15,
    "tokensUsed": 2500,
    "tokensSaved": 12000,
    "savingsPercent": 82.7
  },
  "layer3": {
    "analyse": "...",
    "strategie": "...",
    "decomposition": "...",
    "notes": "..."
  },
  "translation": "oratosa"
}

---

2. Traduire Confluent → FR (lookup direct)

Traduction brute mot-à-mot depuis le Confluent vers le français (sans LLM).

Endpoint : POST /api/translate/conf2fr

Paramètres :

• text (string, requis) : Texte en Confluent
• variant (string, optionnel) : "ancien" (défaut) ou "proto"
• detailed (boolean, optionnel) : Retourner les détails par mot (défaut: false)

Exemple :

curl -X POST https://confluent.etheryale.com/api/translate/conf2fr \
  -H "Content-Type: application/json" \
  -H "X-API-Key: [CLÉ_API]" \
  -d '{
    "text": "nakuura",
    "variant": "ancien"
  }'

Réponse :

{
  "translation": "enfants du courant",
  "coverage": 100,
  "wordsTranslated": 1,
  "wordsNotTranslated": 0
}

---

3. Traduire Confluent → FR (avec raffinage LLM)

Traduction mot-à-mot suivie d'un raffinage par LLM pour un français naturel.

Endpoint : POST /api/translate/conf2fr/llm

Paramètres :

• text (string, requis) : Texte en Confluent
• variant (string, optionnel) : "ancien" (défaut) ou "proto"
• provider (string, optionnel) : "anthropic" (défaut) ou "openai"
• model (string, optionnel) : Modèle à utiliser

Exemple :

curl -X POST https://confluent.etheryale.com/api/translate/conf2fr/llm \
  -H "Content-Type: application/json" \
  -H "X-API-Key: [CLÉ_API]" \
  -d '{
    "text": "nakuura oratosa",
    "variant": "ancien",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }'

Réponse :

{
  "confluentText": "nakuura oratosa",
  "rawTranslation": "enfants du courant bonjour",
  "refinedTranslation": "Les enfants du courant vous saluent",
  "translation": "Les enfants du courant vous saluent",
  "coverage": 100,
  "wordsTranslated": 2,
  "wordsNotTranslated": 0
}

---

4. Rechercher un mot dans le lexique

Recherche bidirectionnelle dans le lexique (FR→CF ou CF→FR).

Endpoint : GET /api/search

Paramètres :

• q (string, requis) : Mot à rechercher
• variant (string, optionnel) : "ancien" (défaut) ou "proto"
• direction (string, optionnel) : "fr2conf" (défaut) ou "conf2fr"

Exemple :

curl "https://confluent.etheryale.com/api/search?q=enfant&variant=ancien&direction=fr2conf" \
  -H "X-API-Key: [CLÉ_API]"

Réponse :

{
  "query": "enfant",
  "variant": "ancien",
  "direction": "fr2conf",
  "results": [
    {
      "mot": "enfant",
      "traductions": [
        {
          "confluent": "kuura",
          "type": "racine",
          "contexte": "jeune humain"
        }
      ]
    }
  ]
}

---

5. Analyser la couverture lexicale

Analyse un texte français pour voir combien de mots sont présents dans le lexique.

Endpoint : POST /api/analyze/coverage

Paramètres :

• text (string, requis) : Texte français à analyser
• target (string, optionnel) : "ancien" (défaut) ou "proto"

Exemple :

curl -X POST https://confluent.etheryale.com/api/analyze/coverage \
  -H "Content-Type: application/json" \
  -H "X-API-Key: [CLÉ_API]" \
  -d '{
    "text": "Les enfants du courant pêchent dans la rivière",
    "target": "ancien"
  }'

Réponse :

{
  "coverage": 85.7,
  "found": [
    {"word": "enfants", "confluent": "nakuura", "type": "composition"},
    {"word": "courant", "confluent": "kuuraa", "type": "racine"}
  ],
  "missing": [
    {"word": "pêchent"}
  ],
  "stats": {
    "totalWords": 7,
    "uniqueWords": 7,
    "foundCount": 6,
    "missingCount": 1
  },
  "recommendation": "Good coverage - context only"
}

---

6. Statistiques du lexique

Récupère les statistiques globales du lexique (endpoint public, pas d'authentification).

Endpoint : GET /api/stats

Paramètres :

• variant (string, optionnel) : "ancien" (défaut) ou "proto"

Exemple :

curl "https://confluent.etheryale.com/api/stats?variant=ancien"

Réponse :

{
  "motsCF": 450,
  "motsFR": 520,
  "totalTraductions": 680,
  "racines": 180,
  "racinesSacrees": 35,
  "racinesStandards": 145,
  "compositions": 250,
  "verbes": 45,
  "particules": 30,
  "nomsPropes": 25
}

---

Utilisation dans du code JavaScript

const API_KEY = '[CLÉ_API]';
const BASE_URL = 'https://confluent.etheryale.com';

// Traduire FR → Confluent
async function translateToConfluent(text) {
  const response = await fetch(`${BASE_URL}/translate`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      text: text,
      target: "ancien",
      provider: "anthropic",
      model: "claude-sonnet-4-20250514"
    })
  });

  const data = await response.json();
  return data.translation;
}

// Traduire Confluent → FR
async function translateFromConfluent(text) {
  const response = await fetch(`${BASE_URL}/api/translate/conf2fr`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      text: text,
      variant: "ancien"
    })
  });

  const data = await response.json();
  return data.translation;
}

// Rechercher un mot
async function searchWord(word) {
  const response = await fetch(
    `${BASE_URL}/api/search?q=${encodeURIComponent(word)}&variant=ancien&direction=fr2conf`,
    {
      headers: {
        'X-API-Key': API_KEY
      }
    }
  );

  const data = await response.json();
  return data.results;
}

---

Notes importantes

• Rate limiting : L'API suit l'utilisation des tokens LLM. Vérifie /api/llm/limit pour connaître ton quota.
• Variantes :
  • "ancien" : Ancien Confluent (langue mature, recommandé)
  • "proto" : Proto-Confluent (langue primitive)
• Provider recommandé : Anthropic (Claude) pour la meilleure qualité de traduction
• Analyse contextuelle : Active par défaut, envoie uniquement les mots pertinents au LLM (économise ~80% de tokens)

---

Ressources

• Interface web : https://confluent.etheryale.com
• Interface admin : https://confluent.etheryale.com/admin.html
• Documentation linguistique : Voir le dépôt confluent/ pour les détails de la langue