REST API & SDK better-i18n : Gestion programmatique des traductions

REST API & SDK better-i18n : Gestion programmatique des traductions

La plateforme better-i18n offre aux développeurs un accès programmatique complet à la gestion des traductions — via un SDK TypeScript, une REST API, des outils CLI et un serveur MCP pour les assistants IA. Gérez les clés, traductions, langues et contenus directement depuis votre code et vos pipelines CI.

Deux APIs, deux usages distincts

better-i18n expose deux APIs différentes selon ce que vous construisez :

Les deux APIs utilisent des corps JSON en requête/réponse et suivent les conventions REST.

Authentification

Générez des clés API dans Paramètres → Clés API sur votre tableau de bord.

# Translation API (gestion des clés, traductions)
curl -H "Authorization: Bearer bi18_live_abc123..." \
  https://dash.better-i18n.com/api/...

# Content API (CMS headless)
curl -H "x-api-key: bi-your-api-key" \
  https://content.better-i18n.com/v1/content/acme/web-app/models

N'exposez jamais vos clés API côté client. Utilisez des variables d'environnement et des proxies côté serveur.

Translation API

La Translation API gère le flux i18n principal : projets, clés, traductions et langues.

Projets

listProjects()          → Lister tous les projets auxquels vous avez accès
getProject(project)     → Obtenir les détails, langues et namespaces d'un projet

Chaque projet est identifié au format org/projet (ex. acme/web-app). Vous le trouverez dans votre i18n.config.ts.

Clés de traduction

listKeys(project, options)    → Rechercher et parcourir les clés de traduction
createKeys(project, keys)     → Créer des clés avec texte source et traductions
updateKeys(project, updates)  → Mettre à jour les traductions de clés existantes
deleteKeys(project, keys)     → Suppression douce des clés de traduction

Créer des clés avec traductions en un seul appel :

{
  "project": "acme/web-app",
  "keys": [
    {
      "name": "auth.login.title",
      "namespace": "auth",
      "sourceText": "Sign in to your account",
      "translations": {
        "tr": "Hesabınıza giriş yapın",
        "de": "Melden Sie sich bei Ihrem Konto an"
      }
    },
    {
      "name": "auth.login.button",
      "namespace": "auth",
      "sourceText": "Sign in"
    }
  ]
}

Rechercher et filtrer les clés :

{
  "project": "acme/web-app",
  "search": "login",
  "namespaces": ["auth"],
  "missingLanguage": "tr"
}

Mettre à jour les traductions avec un statut :

{
  "project": "acme/web-app",
  "translations": [
    {
      "key": "auth.login.title",
      "language": "tr",
      "text": "Hesabınıza giriş yapın",
      "status": "approved"
    }
  ]
}

Langues

addLanguage(project, language)   → Ajouter une nouvelle langue cible
getProject(project)              → Voir toutes les langues actives et leur progression

Opérations de synchronisation

getSyncs(project)    → Lister les opérations de sync récentes (GitHub, CDN, etc.)
getSync(project, id) → Obtenir les détails d'un job de sync spécifique

Content SDK

Le @better-i18n/sdk est un client TypeScript pour la Content API — notre CMS headless pour les contenus structurés comme les articles de blog, les entrées de changelog et les pages marketing.

Installation

npm install @better-i18n/sdk

Initialisation

import { createClient } from "@better-i18n/sdk";

const client = createClient({
  project: "acme/web-app",
  apiKey: process.env.BETTER_I18N_API_KEY!,
});

Query Builder (style Supabase)

Le SDK fournit un query builder chaînable et immuable :

// Lister les articles de blog publiés
const { data: posts, total, hasMore } = await client
  .from("blog-posts")
  .eq("status", "published")
  .order("publishedAt", { ascending: false })
  .expand("author", "category")
  .limit(10);

// Obtenir une entrée unique en français
const { data: post } = await client
  .from("blog-posts")
  .language("fr")
  .single("getting-started");

console.log(post.title, post.body);

Méthodes disponibles

Endpoints REST (sous le capot)

Le SDK appelle ces endpoints :

Outils CLI

Le @better-i18n/cli s'intègre dans votre workflow de développement :

# Détecter les chaînes en dur dans votre codebase
better-i18n scan

# Comparer les clés locales avec le projet cloud
better-i18n sync

# Intégration CI/CD avec sortie JSON
better-i18n scan --ci --format json
better-i18n sync --format json

Le CLI détecte automatiquement les hooks useTranslations() et getTranslations(), extrait les namespaces et signale les traductions manquantes — en moins de 100 ms pour les codebases typiques.

Intégration pre-commit & CI

# Hook pre-commit
npx @better-i18n/cli scan --staged --ci

# GitHub Actions
- run: npx @better-i18n/cli scan --ci --format json

Serveur MCP pour assistants IA

Le serveur MCP (Model Context Protocol) better-i18n permet aux assistants IA comme Claude, Cursor et Windsurf de gérer les traductions directement depuis votre IDE :

# Installer le serveur MCP
npm install @better-i18n/mcp

Les assistants IA peuvent :

• Lister et rechercher des clés de traduction
• Créer de nouvelles clés avec traductions
• Mettre à jour les traductions existantes
• Vérifier le statut de synchronisation
• Ajouter de nouvelles langues

Cela signifie que vous pouvez dire « Ajoute les traductions allemandes pour le namespace auth » et votre assistant IA s'en charge via l'API.

Diffusion via CDN

Les traductions sont servies mondialement via notre CDN avec un schéma d'URL prévisible :

https://cdn.better-i18n.com/{org}/{project}/{locale}/{namespace}.json

Par exemple :

https://cdn.better-i18n.com/acme/web-app/de/common.json

Aucun déploiement nécessaire — les traductions se mettent à jour sur le CDN automatiquement à la publication.

SDKs par plateforme

Tous les packages sont disponibles sur npm et fonctionnent dans tout runtime JavaScript avec fetch() natif.

Ressources associées

• Intégration Git — Synchronisez vos traductions avec votre dépôt via des pull requests
• Webhooks & Événements — Notifications en temps réel pour les événements de traduction
• Documentation API complète — Référence complète des endpoints