Papermark je open-source platforma pro sdílení dokumentů. Když se tým rozhodl lokalizovat svou dokumentaci, narazil na problém, který zastaví většinu týmů vyvíjejících nástroje pro vývojáře: správně zprovoznit i18n v aplikaci postavené na Next.js je těžší než samotný překlad.

Problém s nasazením#

„Vyzkoušela jsem všechny automatizační balíčky i vlastní nástroje, které byly k dispozici,“ vzpomíná Iuliia Shnai, zakladatelka Papermark. „Největší problém nebyl ani samotný překlad – bylo to zprovoznit i18n tak, aby správně fungovalo s naší strukturou aplikace.“

Tohle je známý scénář. Většina lokalizačních nástrojů předpokládá, že i18n infrastruktura už je hotová. Umí překlad. Neřeší ale konfiguraci, strukturu souborů, parsování MDX ani hraniční případy, které se liší framework od frameworku. Pro open-source projekt s malým týmem je čas věnovaný inženýringu kolem nastavení lokalizace přímým nákladem na produkt.

Další vrstvu složitosti přidávají soubory MDX – dokumentace psaná v Markdownu s vloženými React komponentami. Běžné i18n nástroje pracují se soubory JSON pro jednotlivé jazyky a s jednoduchými řetězci. MDX obsah s interpolacemi komponent, frontmatterem a vlastními tagy vyžaduje jiný přístup.

Co se změnilo#

Max, zakladatel Lingo.dev, se ozval přímo a pomohl nakonfigurovat projekt Papermarku na Next.js. Implementace si poradila s hraničními případy, na kterých se tým zasekl: zpracováním souborů MDX, souhrou mezi next-intl a strukturou souborů aplikace i extrakcí přeložitelných řetězců z dokumentace plné komponent.

„Implementace si poradila s tolika hraničními případy, na které jsme vůbec nepomysleli,“ říká Shnai. „Bylo jasné, že mají všechny složitosti lokalizace opravdu promyšlené, zejména u souborů MDX, které pro nás byly obzvlášť bolestivým místem.“

Už první den: 80 stránek dokumentace přeloženo. Lokalizační engine – nakonfigurovaný s produktovou terminologií Papermarku a propojený s jejich repozitářem – automaticky zpracoval celou dokumentaci.

Jak to funguje dnes#

Lokalizační engine Papermarku běží při každém pushi kódu. Když přibude nová dokumentace nebo se aktualizuje stávající obsah, engine změny automaticky přeloží. Inženýři píšou dokumentaci v angličtině a lokalizované verze se objevují bez jakýchkoli dalších kroků.

Zásadní je tu právě stavovost. Protože lokalizační engine uchovává produktovou terminologii Papermarku napříč všemi požadavky, produktově specifické výrazy jako „Data Room“, „Link tracking“ a „NDA flow“ se překládají konzistentně ve všech jazycích. Jak první stránka dokumentace zpracovaná enginem, tak i ta stou používají stejnou produktovou slovní zásobu.

„Nulové průběžné nasazení inženýringu na překlady“ je měřitelný výsledek – ale skutečný důvod je v tom, že se z lokalizace stala infrastruktura, ne opakující se úkol.

Výsledky#

• 80 stránek dokumentace přeloženo hned první den
• Nulové průběžné nasazení inženýringu na lokalizaci
• Automatické zpracování komplexní MDX dokumentace
• Průběžný překlad při každém pushi, včetně nového i aktualizovaného obsahu
• Konzistentní terminologie ve všech jazycích

U open-source projektu na ekonomice záleží. Každá hodina, kterou není potřeba věnovat údržbě lokalizace, je hodinou navíc pro produkt. Papermark svůj lokalizační engine dál rozšiřuje tak, aby pokryl i SEO optimalizaci napříč jazyky.