better-i18n REST API & SDK: Programmatisches Übersetzungsmanagement

better-i18n REST API & SDK: Programmatisches Übersetzungsmanagement

Die better-i18n-Plattform gibt Entwicklern vollständigen programmatischen Zugriff auf das Übersetzungsmanagement – über ein TypeScript SDK, eine REST API, CLI-Tools und einen MCP-Server für KI-Assistenten. Verwalte Keys, Übersetzungen, Sprachen und Inhalte aus eigenem Code und CI-Pipelines.

Zwei APIs, unterschiedliche Zwecke

better-i18n stellt zwei separate APIs bereit, je nachdem was du entwickelst:

Beide APIs verwenden JSON-Request/Response-Bodies und folgen REST-Konventionen.

Authentifizierung

Erstelle API-Keys unter Einstellungen → API Keys in deinem Dashboard.

# Translation API (Key-Management, Übersetzungen)
curl -H "Authorization: Bearer bi18_live_abc123..." \
  https://dash.better-i18n.com/api/...

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

Exponiere API-Keys niemals in clientseitigem Code. Verwende Umgebungsvariablen und serverseitige Proxys.

Translation API

Die Translation API verwaltet den zentralen i18n-Workflow: Projekte, Keys, Übersetzungen und Sprachen.

Projekte

listProjects()          → Alle zugänglichen Projekte auflisten
getProject(project)     → Projektdetails, Sprachen und Namespaces abrufen

Jedes Projekt wird im Format org/project identifiziert (z. B. acme/web-app). Du findest dies in deiner i18n.config.ts.

Translation Keys

listKeys(project, options)    → Translation Keys suchen und durchsuchen
createKeys(project, keys)     → Keys mit Quelltext und Übersetzungen erstellen
updateKeys(project, updates)  → Übersetzungen für bestehende Keys aktualisieren
deleteKeys(project, keys)     → Translation Keys soft-löschen

Keys mit Übersetzungen in einem einzigen Aufruf erstellen:

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

Keys suchen und filtern:

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

Übersetzungen mit Status aktualisieren:

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

Sprachen

addLanguage(project, language)   → Neue Zielsprache hinzufügen
getProject(project)              → Alle aktiven Sprachen und Fortschritt einsehen

Sync-Operationen

getSyncs(project)    → Aktuelle Sync-Operationen auflisten (GitHub, CDN usw.)
getSync(project, id) → Details eines bestimmten Sync-Jobs abrufen

Content SDK

Das @better-i18n/sdk ist ein TypeScript-Client für die Content API – unser Headless CMS für strukturierte Inhalte wie Blogbeiträge, Changelog-Einträge und Marketing-Seiten.

Installation

npm install @better-i18n/sdk

Initialisierung

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

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

Query Builder (Supabase-Stil)

Das SDK stellt einen verkettbaren, unveränderlichen Query Builder bereit:

// Veröffentlichte Blogbeiträge auflisten
const { data: posts, total, hasMore } = await client
  .from("blog-posts")
  .eq("status", "published")
  .order("publishedAt", { ascending: false })
  .expand("author", "category")
  .limit(10);

// Einzelnen Eintrag auf Französisch abrufen
const { data: post } = await client
  .from("blog-posts")
  .language("fr")
  .single("getting-started");

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

Verfügbare Methoden

REST-Endpunkte (Im Hintergrund)

Das SDK ruft folgende Endpunkte auf:

CLI-Tools

Das @better-i18n/cli integriert sich in deinen Entwicklungsworkflow:

# Hartcodierte Strings in deiner Codebasis erkennen
better-i18n scan

# Lokale Keys mit dem Cloud-Projekt abgleichen
better-i18n sync

# CI/CD-Integration mit JSON-Ausgabe
better-i18n scan --ci --format json
better-i18n sync --format json

Das CLI erkennt automatisch useTranslations()- und getTranslations()-Hooks, extrahiert Namespaces und meldet fehlende Übersetzungen – alles in unter 100 ms für typische Codebasen.

Pre-commit & CI-Integration

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

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

MCP-Server für KI-Assistenten

Der better-i18n MCP-Server (Model Context Protocol) ermöglicht es KI-Assistenten wie Claude, Cursor und Windsurf, Übersetzungen direkt aus deiner IDE zu verwalten:

# MCP-Server installieren
npm install @better-i18n/mcp

KI-Assistenten können:

• Translation Keys auflisten und suchen
• Neue Keys mit Übersetzungen erstellen
• Bestehende Übersetzungen aktualisieren
• Sync-Status prüfen
• Neue Sprachen hinzufügen

Das bedeutet: Du sagst einfach „Füge deutsche Übersetzungen für den auth-Namespace hinzu" und dein KI-Assistent erledigt das über die API.

CDN-Auslieferung

Übersetzungen werden weltweit über unser CDN mit einem vorhersehbaren URL-Muster bereitgestellt:

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

Zum Beispiel:

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

Kein Deploy nötig – Übersetzungen werden automatisch auf dem CDN aktualisiert, sobald sie veröffentlicht werden.

Platform SDKs

Alle Pakete sind auf npm verfügbar und funktionieren in jeder JavaScript-Laufzeitumgebung mit nativem fetch().

Weiterführende Ressourcen

• Git-Integration — Übersetzungen per Pull Request mit deinem Repository synchronisieren
• Webhooks & Events — Echtzeit-Benachrichtigungen für Übersetzungsereignisse
• Vollständige API-Dokumentation — Komplette Endpunkt-Referenz