Inhaltsverzeichnis
API-First-Lokalisierung: Übersetzung in Ihren Entwicklungs-Workflow integrieren
Wichtigste Erkenntnisse
- API-first-Lokalisierung ersetzt den manuellen Dateiaustausch durch automatisierte Synchronisierung zwischen Ihrer Codebasis und dem Translation Management System
- CLI-Tools und CI/CD-Integrationen ermöglichen Push/Pull-Workflows, die Übersetzungen bei jeder Bereitstellung synchron halten
- Webhook-basierte Benachrichtigungen lösen Builds aus, wenn Übersetzungen aktualisiert werden, und ermöglichen so kontinuierliche Lokalisierung
- API-first-Ansätze reduzieren die Time-to-Market für neue Sprachen von Wochen auf Stunden
Was ist API-First-Lokalisierung?
API-first-Lokalisierung ist ein Ansatz, bei dem das Translation Management System (TMS) über REST-APIs, CLI-Tools und Webhooks programmatischen Zugriff auf alle Übersetzungs-Workflows bietet. Anstatt Übersetzungsdateien manuell zu exportieren/importieren, integrieren Entwickler die Übersetzungssynchronisierung direkt in ihre Build- und Deployment-Pipelines.
Traditioneller vs. API-First-Workflow
Traditionell (Dateibasiert)
- Entwickler exportiert Quell-Strings in eine Datei (JSON, XLIFF usw.)
- Datei wird ins TMS hochgeladen oder per E-Mail an Übersetzer gesendet
- Übersetzte Dateien kommen nach Tagen/Wochen zurück
- Entwickler lädt Dateien herunter und legt sie in die richtigen Verzeichnisse
- Entwickler committet und deployt
Probleme: Manuelle Schritte, Versionsdrift, Merge-Konflikte, langsame Zykluszeiten.
API-First
- Entwickler pusht neue Strings per CLI:
better-i18n push - TMS benachrichtigt Übersetzer über neue Inhalte
- Übersetzer arbeiten im TMS-Editor mit vollem Kontext
- Webhook löst CI/CD aus, wenn Übersetzungen abgeschlossen sind
- Build zieht die neuesten Übersetzungen:
better-i18n pull - Deployment enthält aktualisierte Übersetzungen automatisch
Vorteile: Kein manueller Dateiaufwand, kontinuierliche Synchronisierung, schnellere Zykluszeiten.
Kernkomponenten der API-First-Lokalisierung
REST API
Die TMS-API stellt folgende Endpunkte bereit:
POST /api/keys — Neue Übersetzungsschlüssel erstellen GET /api/translations — Übersetzungen für ein Locale abrufen PUT /api/translations — Übersetzungen aktualisieren GET /api/projects — Projekte und deren Status auflisten POST /api/upload — Quelldateien hochladen GET /api/download — Übersetzte Dateien herunterladen
CLI-Tool
Ein Kommandozeilen-Tool, das die API für Entwickler kapselt:
# Neue Quell-Strings ins TMS pushen better-i18n push # Neueste Übersetzungen ziehen better-i18n pull --locale=de,fr,ja # Übersetzungsstatus prüfen better-i18n status # Codebasis nach nicht übersetzten Strings durchsuchen better-i18n scan
Webhooks
Ereignisgesteuerte Benachrichtigungen bei Änderungen an Übersetzungen:
{
"event": "translations.completed",
"project": "my-app",
"locale": "de",
"completed_keys": 142,
"total_keys": 142
}
Verwenden Sie Webhooks, um CI/CD-Pipelines, Slack-Benachrichtigungen oder automatisierte Deployments auszulösen.
CI/CD-Integration
Integrieren Sie die Übersetzungssynchronisierung in Ihre Build-Pipeline:
# GitHub Actions Beispiel
- name: Pull translations
run: better-i18n pull --all
env:
BETTER_I18N_TOKEN: ${{ secrets.BETTER_I18N_TOKEN }}
- name: Build
run: npm run build
Vorteile der API-First-Lokalisierung
| Vorteil | Auswirkung |
|---|---|
| Automatisierte Synchronisierung | Kein manuelles Dateimanagement |
| Versionskontrolle | Übersetzungen werden zusammen mit dem Code verfolgt |
| Continuous Delivery | Neue Übersetzungen werden mit jedem Deployment ausgeliefert |
| Entwicklererfahrung | Vertrauter CLI/API-Workflow |
| Schnellere Time-to-Market | Neue Sprachen in Stunden statt Wochen |
| Weniger Fehler | Keine Dateiformat-Probleme oder falsch abgelegte Dateien |
Implementierungsmuster
Muster 1: Build-Time Pull
Übersetzungen werden während des Build-Schritts gezogen. Übersetzungen werden beim Build in die App gebündelt.
Am besten geeignet für: Statische Websites, vorgerenderte Seiten, mobile Apps.
Muster 2: Runtime Fetch
Übersetzungen werden zur Laufzeit von der API abgerufen. Ermöglicht sofortige Updates ohne erneutes Deployment.
Am besten geeignet für: SPAs, dynamische Web-Apps, Echtzeit-Inhalte.
Muster 3: Hybrid
Übersetzungen werden zum Build-Zeitpunkt für das initiale Laden gezogen, Updates werden zur Laufzeit für Hotfixes abgerufen.
Am besten geeignet für: Produktions-Apps, die sowohl Performance als auch Flexibilität benötigen.
FAQ
Muss ich mein Dateiformat ändern, um API-first-Lokalisierung zu nutzen? Nein. Die meisten API-first-TMS-Plattformen unterstützen Standardformate (JSON, XLIFF, YAML, .strings, .xml) und führen die Formatkonvertierung automatisch durch.
Wie gehe ich mit Übersetzungsschlüsseln um, die umbenannt oder gelöscht werden?
Der CLI-Befehl scan erkennt unbenutzte Schlüssel. API-Endpunkte ermöglichen Batch-Schlüsseloperationen. Die meisten TMS-Plattformen verfolgen den Schlüssel-Lebenszyklus und markieren verwaiste Übersetzungen.
Was passiert, wenn die API während eines Builds nicht erreichbar ist? Verwenden Sie zwischengespeicherte Übersetzungen als Fallback. Speichern Sie den letzten erfolgreichen Pull in der Versionskontrolle, damit Builds immer eine Basis haben, auch wenn die API nicht erreichbar ist.
Wie verwalte ich Übersetzungen für mehrere Umgebungen? Verwenden Sie Namespacing auf Projekt- oder Branch-Ebene. Einige TMS-Plattformen unterstützen umgebungsspezifische Overrides (Staging, Production) für dasselbe Projekt.
Ist API-first-Lokalisierung für kleine Projekte geeignet? Ja. Der CLI-Push/Pull-Workflow ist selbst für Projekte mit wenigen hundert Strings einfacher als manuelles Dateimanagement. Der Aufwand für die Einrichtung der API-Integration ist minimal im Vergleich zur eingesparten Zeit.
