Papermark ist eine Open-Source-Plattform zum Teilen von Dokumenten. Als das Team beschloss, seine Dokumentation zu lokalisieren, stieß es auf genau das Problem, an dem die meisten Entwicklertool-Teams scheitern: i18n in einer Next.js-Anwendung sauber zum Laufen zu bringen, ist schwieriger als die Übersetzung selbst.

Das Setup-Problem#

„Ich habe jedes Automatisierungspaket und jedes selbst gebaute Tool ausprobiert“, erinnert sich Iuliia Shnai, Gründerin von Papermark. „Der größte Schmerzpunkt war nicht einmal die Übersetzung – sondern i18n sauber in unsere App-Struktur zu integrieren.“

Das ist ein bekanntes Muster. Die meisten Lokalisierungstools setzen voraus, dass die i18n-Infrastruktur bereits steht. Sie kümmern sich um die Übersetzung. Nicht aber um Konfiguration, Dateistruktur, MDX-Parsing oder die frameworkspezifischen Sonderfälle. Für ein Open-Source-Projekt mit kleinem Team sind Engineering-Stunden, die in das Lokalisierungs-Setup fließen, direkte Kosten fürs Produkt.

MDX-Dateien – also in Markdown geschriebene Dokumentation mit eingebetteten React-Komponenten – machen das Ganze noch komplexer. Standardmäßige i18n-Tools arbeiten mit JSON-Sprachdateien und einfachen Strings. MDX-Inhalte mit Komponenten-Interpolationen, Frontmatter und benutzerdefinierten Tags erfordern einen anderen Ansatz.

Was sich geändert hat#

Max, der Gründer von Lingo.dev, meldete sich direkt und half dabei, Papermarks Next.js-Projekt zu konfigurieren. Die Implementierung löste genau die Sonderfälle, an denen das Team festhing: die Verarbeitung von MDX-Dateien, das Zusammenspiel von next-intl mit der Dateistruktur der App und die Extraktion übersetzbarer Strings aus komponentenlastiger Dokumentation.

„Die Implementierung hat so viele Sonderfälle abgedeckt, an die wir gar nicht gedacht hatten“, sagt Shnai. „Es war sofort klar, dass sie die ganze Komplexität von Lokalisierung durchdrungen hatten – besonders bei MDX-Dateien, die für uns ein echter Schmerzpunkt waren.“

Am ersten Tag: 80 Dokumentationsseiten übersetzt. Die Lokalisierungs-Engine – konfiguriert mit Papermarks Produktterminologie und mit dem Repository verbunden – übernahm automatisch die gesamte Dokumentation.

So läuft es heute#

Papermarks Lokalisierungs-Engine läuft bei jedem Code-Push. Sobald neue Dokumentation hinzukommt oder bestehende Inhalte aktualisiert werden, übersetzt die Engine die Änderungen automatisch. Engineers schreiben die Dokumentation auf Englisch; lokalisierte Versionen erscheinen ohne zusätzlichen Aufwand.

Entscheidend ist hier die Statefulness. Weil die Lokalisierungs-Engine Papermarks Produktterminologie über jede Anfrage hinweg beibehält, werden produktspezifische Begriffe wie „Data Room“, „Link tracking“ und „NDA flow“ in allen Sprachen konsistent übersetzt. Ob die erste Dokumentationsseite durch die Engine läuft oder die hundertste: Es gilt immer derselbe Produktwortschatz.

„Kein laufender Engineering-Aufwand für Übersetzungen“ ist das messbare Ergebnis – der eigentliche Grund dahinter ist jedoch, dass Lokalisierung von einer wiederkehrenden Aufgabe zu Infrastruktur geworden ist.

Ergebnisse#

• 80 Dokumentationsseiten am ersten Tag übersetzt
• Kein laufender Engineering-Aufwand für Lokalisierung
• Automatische Verarbeitung komplexer MDX-Dokumentation
• Kontinuierliche Übersetzung bei jedem Push – für neue und aktualisierte Inhalte
• Konsistente Terminologie in allen Sprachen

Für ein Open-Source-Projekt zählt die Wirtschaftlichkeit. Jede Stunde, die nicht in die Pflege der Lokalisierung fließt, ist eine Stunde mehr fürs Produkt. Papermark baut seine Lokalisierungs-Engine weiter aus, um auch die SEO-Optimierung über verschiedene Sprachen hinweg abzudecken.