Docs-as-Code international: So automatisierten wir die japanische GitLab-Dokumentation

Vor ein paar Tagen haben wir die GitLab-Produktdokumentation auf Japanisch unter docs.gitlab.com/ja-jp veröffentlicht. Dieser Schritt markiert den Beginn unserer Initiative, die umfassende GitLab-Dokumentation weltweit zugänglich zu machen.

Die besondere Herausforderung des japanischen Marktes

Japan gehört zu den größten Wirtschaftsräumen weltweit und stellt einen wichtigen Markt für Unternehmenssoftware dar. Trotz hoher technischer Kompetenz und einer großen Entwickler-Community kann die Sprachbarriere bei englischsprachiger Dokumentation für viele Nutzer eine Herausforderung darstellen.

Entwicklungsteams und DevSecOps-Teams haben uns direkt mitgeteilt, dass englischsprachige Dokumentation nicht nur eine Unannehmlichkeit, sondern ein Hindernis darstellt, um GitLab optimal zu nutzen. Die Auswirkungen zeigen sich in jeder Phase: Von der initialen Evaluierung, bei der Teams GitLabs Funktionen schwerer einschätzen können, über den täglichen Betrieb, bei dem das Finden von Lösungen länger dauert, bis hin zur Aktualisierung mit neuen Features und Best Practices.

In wettbewerbsintensiven Märkten beeinflusst diese Sprachbarriere direkt die Marktdurchdringung. Bei der Evaluierung von Unternehmenssoftware signalisiert die Verfügbarkeit umfassender muttersprachlicher Dokumentation ein langfristiges Markt-Commitment. Sie zeigt, dass ein Anbieter nicht nur symbolische Anstrengungen unternimmt, sondern genuines Interesse hat, Nutzer während ihrer gesamten Journey zu unterstützen.

Um diese Herausforderung zu adressieren, haben wir eine Lokalisierungs-Infrastruktur von Grund auf entwickelt, die mit unserer Methode zur Erstellung und Pflege von Dokumentation bei GitLab integriert ist.

Lokalisierung auf Basis von docs-as-code-Prinzipien

GitLabs Dokumentation wird wie jeder andere Code-Beitrag behandelt: Sie befindet sich neben dem Produktcode in GitLab-Projekten und wird über Merge Requests verwaltet. Dieses System stellt sicher, dass Dokumentation versionskontrolliert, kollaborativ reviewt und automatisch durch CI/CD-Pipelines getestet wird. Tests prüfen auf Probleme mit Sprache, Formatierung und Links. Die englischsprachige und japanische Dokumentationsseite werden dynamisch mit dem Hugo Static Site Generator generiert und nach dem Mergen von Änderungen deployed, sodass Nutzer stets Zugriff auf aktuelle Informationen haben.

Der docs-as-code-Ansatz stellt einen systematischen Rahmen für die Verwaltung mehrsprachiger Dokumentation bereit. Durch die Behandlung von Dokumentation als Code – mit Versionskontrolle, automatisierten Tests und CI/CD-Pipelines – entsteht eine reproduzierbare, skalierbare Infrastruktur. Dieser methodische Ansatz reduziert manuelle Koordinationsaufwände und gewährleistet konsistente Qualitätsstandards über alle Sprachen hinweg.

Die Dokumentation ist umfangreich und zieht Inhalte aus verschiedenen Quellprojekten: GitLab, GitLab Runner, Omnibus GitLab, GitLab Charts, GitLab Operator und GitLab CLI (glab) (Details zur Architektur). Diese Größenordnung und hohe Update-Frequenz stellten eine erhebliche Lokalisierungsherausforderung dar. Um mit der kontinuierlichen Entwicklung dieser englischen Quellprojekte Schritt zu halten, mussten wir eine Lokalisierungs-Infrastruktur entwickeln, die diese Komplexitäten bewältigt, eine vollständig lokalisierte Seite auf Enterprise-Niveau bereitstellt und gleichzeitig unsere CI/CD-Pipeline-Anforderungen erfüllt.

Wie wir GitLab-Dokumentation lokalisiert haben

Für unsere initiale japanische Lokalisierung haben wir eine Strategie gewählt, bei der neue Ordner in die bestehende englische Content-Struktur integriert werden. Konkret haben wir doc-locale/ja-jp-Ordner in jedem Projekt eingeführt, das Markdown-Quelldateien speichert. Diese Architektur hält die Übersetzungen direkt neben ihrem Quellcontent und bewahrt gleichzeitig eine klare organisatorische Trennung. Das ermöglicht uns, dieselbe robuste Versionskontrolle, etablierte Review- und Kollaborations-Workflows und sogar einige der automatisierten Qualitätschecks, die für unsere englische Dokumentation verwendet werden, auf den übersetzten Content anzuwenden.

Diese für japanische Dokumentation entwickelte Internationalisierungs-Infrastruktur bietet eine skalierbare Grundlage für zukünftige Spracherweiterungen. Mit der nun vorhandenen Architektur, den Tools und Prozessen sind wir gut positioniert, zusätzliche Sprachen zu unterstützen und unser Commitment fortzusetzen, GitLab weltweit zugänglich zu machen.

Ein KI-gestützter Übersetzungs-Workflow, der Geschwindigkeit und Qualität ausbalanciert

Wir haben einen strategischen, phasenweisen Ansatz für die Content-Verarbeitung durch Übersetzung gewählt und Seiten basierend auf ihren englischsprachigen Page Views priorisiert. Die am häufigsten besuchten Seiten durchliefen zuerst die KI-Übersetzung, gefolgt von umfassendem linguistischem Human-Review. Wir haben nachfolgende Phasen bewusst pausiert, bis diese Prioritätsseiten den vollständigen Human-Review-Zyklus abgeschlossen hatten. Diese bewusste Sequenzierung ermöglichte es uns, ein robustes, kuratiertes Translation Memory und eine Termbase aus unserem wichtigsten Content aufzubauen. Diese linguistischen Assets beschleunigten und verbesserten die Qualität über den gesamten verbleibenden Content hinweg. Parallel diente diese initiale Phase als Testumgebung für die technische Infrastruktur auf GitLab-Seite. Wir nutzten sie, um unsere CI/CD-Pipelines iterativ zu stärken, unsere Übersetzungs- und Post-Editing-KI-Skripte zu verfeinern und unseren Translation-MR-Review-Prozess zu festigen.

Um internationalen Nutzern die aktuellste Dokumentation bereitzustellen und gleichzeitig hochqualitativen übersetzten Content zu garantieren, haben wir einen KI-gestützten Übersetzungs-Workflow mit Human-Post-Editing implementiert:

• Phase 1: KI-gestützte Übersetzung. Wir haben ein maßgeschneidertes KI-Übersetzungssystem entwickelt, das mit GitLab-spezifischem Kontext angereichert ist: Style Guides, GitLab-UI-Content-Übersetzungen, Terminologiedatenbanken und Original-File-Context. Dieses System verarbeitet intelligent GitLabs spezialisierte Markdown-Syntax (GLFM) und schützt Elemente wie Placeholder-Variablen, Alert-Boxen, Hugo-Shortcodes und GitLab-spezifische Referenzen, die Standard-Übersetzungstools nicht standardmäßig verarbeiten können.
• Phase 2: Linguistisches Human-Review. Professionelle japanische Übersetzer, die auf technischen Content spezialisiert sind, reviewen und verfeinern die KI-Übersetzungen. Sie arbeiten mit GitLabs japanischem Style Guide, Translation Memory und Terminologiedatenbank, um Genauigkeit, natürlichen Sprachfluss und kulturelle Angemessenheit sicherzustellen. Diese human-reviewten Übersetzungen ersetzen progressiv die KI-Versionen auf der Seite.

Technische Herausforderungen und Lösungen

Die Lokalisierung von GitLabs umfangreicher Dokumentation unter Beibehaltung unserer docs-as-code-Prinzipien und des CI/CD-getriebenen Publishing-Workflows erforderte erhebliche technische Innovation. Die Herausforderungen gingen über die Übersetzung selbst hinaus: Wir mussten komplexe Markdown-Syntax bewahren, automatisierte Testing-Standards aufrechterhalten, nahtlose Content-Fallbacks sicherstellen und nachhaltige Prozesse für kontinuierliche Updates über mehrere Quellprojekte hinweg schaffen.

Die Komplexität der englischen Markdown-File-Syntax führte dazu, dass wir Custom-Code und Regex in unserem Translation Management System (TMS) entwickelten, um Codeblocks, URLs und andere funktionale Elemente zu schützen, die nicht für Übersetzung exponiert werden sollten.

Aufgrund der Dynamik der englischen Content-Generierung haben wir einen englischen Fallback-Mechanismus etabliert. Wenn die japanische Übersetzung noch nicht bereit ist, zeigt die lokalisierte Seite nahtlos englischen Content mit übersetzter Navigation und UI an, verhindert 404-Fehler und bewahrt den Sprachkontext über Hugos Rendering-System.

Wir haben die lokalisierte Navigation und Verlinkung verbessert, sodass sie sich dynamisch anpasst und die Locale beibehält. Wir haben Anchor-IDs in den übersetzten Dateien hinzugefügt, indem wir die englische Datei vor dem Senden zur Übersetzung vorverarbeitet haben. Das verbessert die Experience für Personen, die von einem Link zu einer Docs-Seite navigieren. Die konsistente Anchor-ID bedeutet, dass sie zwischen beiden Sprachen wechseln können und dennoch an der korrekten Stelle auf der Seite landen.

Wir haben auch CI/CD-Pipelines erweitert, um lokalisierten Content in Translation-MRs nach denselben Qualitätsstandards wie die englischen Docs zu testen. Das ermöglicht es uns, invalide Hugo-Shortcodes, Spaces innerhalb von Links oder bare URLs zu erkennen. Es identifiziert auch verwaiste Dateien und Redirect-Dateien ohne Target-Dateien. Die Jobs, die auf MRs mit übersetzter Dokumentation laufen, lassen sich in der GitLab-Projekt-.gitlab/ci/docs.gitlab-ci.yml-Datei einsehen.

Ein zentralisiertes Translation-Request-System orchestriert den Workflow: Es überwacht die englischen Dateien, identifiziert neuen und aktualisierten Content, routet Dateien zur Übersetzung, erstellt automatisch Translation-Merge-Requests, trackt den File-Status in Translation-Requests und pflegt einen Audit-Trail. Um die Docs zu übersetzen, haben wir 430 Translation-MRs verarbeitet mit jeweils 1-10 Dateien pro Translation-MR.

Die Git-basierte Versionskontrolle liefert automatische Audit-Trails für alle Dokumentationsänderungen und erfüllt damit Anforderungen aus ISO 27001 Anhang A.12.4.1. Jede Änderung ist mit Zeitstempel, Autor und Commit-Historie nachvollziehbar – eine wertvolle Eigenschaft für Compliance-Audits und Qualitätssicherung in regulierten Branchen. Die 430 verarbeiteten Merge Requests dokumentieren den vollständigen Prozess lückenlos.

Das Ergebnis ist eine japanische Dokumentations-Experience, die mit englischen Content-Updates synchronisiert bleibt und Nutzern schnelleren Zugriff auf kritische Informationen bietet. Nutzer können Content vollständig in ihrer Sprache entdecken und navigieren, wobei Englisch nur für Content erscheint, der sich noch in Übersetzung befindet. Sie können GitLabs Qualitätsstandards vertrauen und gleichzeitig schnell auf die neuesten Features zugreifen. All dies schafft eine nachhaltige, skalierbare Grundlage für zukünftige Sprachen und Dokumentationswachstum.

Die für japanische Dokumentation entwickelte Architektur ist sprachunabhängig und lässt sich direkt auf andere Sprachen übertragen. Der technische Stack (GitLab CI/CD, Hugo, Git) funktioniert identisch für deutsche, französische oder spanische Dokumentation. Nur die Translation-Memory-Inhalte und Terminologiedatenbanken unterscheiden sich – die zugrundeliegende Infrastruktur und Automatisierung bleiben gleich.

Weitere technische Details finden sich auf unserer GitLab Product Documentation Handbook-Seite.

Besuche unsere japanische Docs-Seite

Ob langjähriger GitLab-Nutzer oder gerade erst am Start: Wir hoffen, dass diese lokalisierte Dokumentation die DevSecOps-Journey reibungsloser und zugänglicher macht.

Dies ist erst der Anfang unserer Lokalisierungsanstrengungen, und dein Feedback ist wichtig, um uns zu verbessern. Bei Übersetzungsproblemen, Verbesserungsvorschlägen oder einfach um Erfahrungen mit der japanischen Dokumentation zu teilen: Bitte melde dich. Kommentare können in unserem Feedback-Issue hinterlassen werden.

Während wir diese Lokalisierungs-Infrastruktur weiterentwickeln, umfassen unsere unmittelbaren Prioritäten die Verbesserung der Sucherfahrung für japanische Nutzer und die Beschleunigung unseres kontinuierlichen Lokalisierungs-Workflows, um die Zeitlücke zwischen englischen Updates und ihren japanischen Übersetzungen zu minimieren. Danke an unsere japanische Community für die kontinuierliche Unterstützung und Geduld, während wir daran arbeiten, euch besser zu dienen. Wir sind committed, GitLab zur besten DevSecOps-Plattform für japanische Teams zu machen, und umfassende japanische Dokumentation ist ein wichtiger Schritt auf dieser Journey.

Jetzt erkunden unter docs.gitlab.com/ja-jp!