Auf dieser Seite
Übersetzungen im Release-Takt: der Two-Phase-Rollout
Wenn Übersetzungen im Software-Repository entstehen, aber aus einem Content-Management-System ausgeliefert werden, gibt es bei jedem Release ein Zeitproblem. Werden Textänderungen zu früh eingespielt, überschreiben sie, was gerade live ist. Kommen sie zu spät, sehen Kundinnen und Kunden einen technischen Schlüssel oder eine Textlücke statt der passenden Übersetzung.
Bei 22 Sprachen passierte das nicht selten, sondern regelmäßig. Ich habe deshalb in einem Kundenprojekt aus eigenem Antrieb ein Tool für Entwickler:innen gebaut, um diese Risiken zu minimieren.
Faktor Mensch
Menschen machen Fehler, vergessen oder sind undiszipliniert, erst recht unter Druck. Niemand sollte eine Liste von geänderten Texten von Hand führen. Was solch ein manueller Prozess zur Folge hat, habe ich im Projekt selbst festgestellt, bevor ich die Verbesserung im Team eingeführt habe: Entwickler:innen vergaßen, Änderungen an Texten, die sie im Rahmen einer Aufgabe umgesetzt hatten, an der richtigen Stelle oder gar gänzlich zu dokumentieren.
Die Folge habe ich oben angerissen, und sie ist so einfach wie fatal: fehlende Übersetzungen – den Endkund:innen angezeigt, entweder in Form von technischen Platzhaltern (mit hoffentlich fachlich eindeutigem Namen) oder Textlücken. Entsprechend fehlende Texte in 22 Sprachen für diverse Länder.
Der Kern des Tools ist eine einfache Regel: der Two-Phase-Rollout.
Der Two-Phase-Rollout
Jede Änderung an einem Text ist eine von drei Arten: ein neuer Schlüssel mit Übersetzungstext, ein geänderter Text oder ein gelöschter Schlüssel. Sie sind unterschiedlich gefährlich:
| Änderung | Risiko, wenn zu früh ausgerollt | Phase |
|---|---|---|
| Neuer Schlüssel | Keins. Der alte Code kennt den Schlüssel nicht. | 1 |
| Geänderter Text | Der Live-Code zeigt den neuen Text im alten Zusammenhang. | 2 |
| Gelöschter Schlüssel | Der Live-Code findet seinen Text nicht mehr. | 2 |
Änderungen an Texten werden in zwei Phasen ausgerollt. Phase 1 läuft nach Erstellung des Softwarepakets auf allen Umgebungen, auch in der Produktion: Es werden nur neue Schlüssel mit deren Text angelegt. Phase 2 wird je Umgebung erst dann ausgerollt, wenn die passende Release-Version dort wirklich läuft, also nach dem Deployment des Softwarepakets: Hier folgen die Änderungen und das Löschen von Übersetzungen – denn auch das Aufräumen gehört zur Wartung von Software und deren Inhalten.
Damit ist der gefährliche Teil an das Deployment gekoppelt und der harmlose davon entkoppelt.
Änderungen aus dem Git-Verlauf ableiten
Das Werkzeug vergleicht die Übersetzungsdateien zwischen Zuständen in der Git-Versionierung und sortiert jede Abweichung in eine der drei Arten ein, in Code vereinfacht dargestellt wie folgt:
type Change = { key: string; kind: 'ADD' | 'UPDATE' | 'REMOVE' };
function classify(before: Record<string, string>, after: Record<string, string>): Change[] {
const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
return [...keys].flatMap((key): Change[] => {
if (!(key in before)) return [{ key, kind: 'ADD' }];
if (!(key in after)) return [{ key, kind: 'REMOVE' }];
return before[key] === after[key] ? [] : [{ key, kind: 'UPDATE' }];
});
}Aus den Commits liest es außerdem die Ticketnummer. Das Ergebnis ist ein Changeset, in dem bei jedem Text steht, zu welchem Ticket er gehört. Welche Version auf welcher Umgebung läuft, erkennt das Werkzeug selbst.
Was das Werkzeug sonst noch können muss
- Manuelle Änderungen schützen. Redakteurinnen und Redakteure korrigieren Texte direkt im CMS. Solche Änderungen erkennt das Werkzeug und überschreibt sie nicht stillschweigend.
- In beide Richtungen arbeiten. Texte fließen vom Repository ins CMS und zurück. Der Rückweg legt lokale Änderungen beiseite, übernimmt die Texte und stellt die Änderungen wieder her.
- Aufräumen. Schlüssel, die der Code nicht mehr verwendet, lassen sich finden und entfernen. Dynamisch zusammengesetzte Schlüssel erkennt das Werkzeug und lässt sie stehen.
- Trocken laufen. Jeder schreibende Befehl zeigt zuerst, was er tun würde. Damit ist ein Review durch den Menschen möglich.
Der Teil, der kein Code ist
Ein Werkzeug löst das Problem nur, wenn alle Beteiligten den Ablauf kennen. Ich habe den Prozess deshalb gemeinsam mit dem Content-Team in einem Vortrag vorgestellt, vor Produktverantwortlichen, Fachanalyse und Entwicklung: Wo entstehen Texte, wer gibt sie frei, was passiert beim Release und was im Fehlerfall.
Seitdem ist aus Skripten in einem Repository ein eigenständiges, versioniertes Paket geworden, das sich über Konfiguration an andere Projekte anpassen lässt: Namensräume, Umgebungen, Sprachen und das Muster der Ticketnummern.
Was ich daraus mitnehme
Die technische Umsetzung war auch hier der kleinere Teil. Die Arbeit steckte in der Konzeption und Kommunikation. Die drei Arten von Änderungen zu unterscheiden und zu erkennen, dass nur zwei davon auf das Deployment warten müssen, war der erste logische Schritt zur integrativen Lösung. Mehr dazu im Fallbeispiel.