Japanese product documentation

What

GitLab's product is localized. Its documentation was not — which meant that in GitLab's largest non-English markets, a customer could use the product in their own language and then hit a wall of English the moment they needed to look something up. Research is unambiguous that prospective customers are more likely to buy when they can do so in their native language, and the competitive baseline had already moved: GitHub began localizing its docs in 2022 and now ships eight languages.

Localization and Technical Writing partnered on a programme to localize the documentation site for GitLab's tier-one markets — Japanese, German and French — starting with Japanese, after the docs site's migration to Hugo made a multilingual build possible at all.

I worked the engineering side: the site plumbing that makes a second language behave correctly, the cross-domain handoff from gitlab.com/help, and the launch itself.

How

Turning the locale on was one line. Earning the right to flip it took fourteen months. The merge request that launched Japanese set disabled: false for the ja-jp language in config/_default/hugo.yaml. Everything interesting was in what had to be true first.

Fixing the language selector before anyone used it. The selector originally dropped you at the top of the target-language page. On documentation — where a reader is usually deep in a specific section of a very long page — that is a quietly infuriating bug. I changed onLanguageSelect to carry the current page hash across, so #global-keywords on the English page lands you at /ja-jp/ci/yaml/#global-keywords. Translated pages keep English anchor IDs, so this works today; where a page has no matching anchor, it degrades to loading at the top instead of breaking. Shipped in September, three months ahead of launch, so it was never part of launch-day risk.

Chasing the /help → docs.gitlab.com handoff. The subtle risk wasn't the docs site — it stores no language preference — it was gitlab.com, which does. A user with a Japanese preference on gitlab.com clicking through to the docs site crosses a domain boundary where browsers can do surprising things. Investigating this turned up a genuine constraint: the docs site has no staging environment beyond review apps, and /help is normally only exercised in GDK. So verification had to be assembled out of review apps and local GDK runs rather than a staging environment that did not exist.

Launching on a clock, in the right timezone. The deploy was scheduled for noon PST on Wednesday 10 December 2025 — 05:00 JST on the 11th, so Japanese readers would wake up to it rather than watch it appear mid-afternoon. The launch was split into three tracked pieces with separate owners: site deployment, monitoring and QA during and after launch, and the announcement blog post. The GTM launch epic collected the QA rounds, bug fixes and internal and external communications in one place, so post-launch feedback had somewhere to land.

Outcomes

• docs.gitlab.com/ja-jp is live, and Japanese is the first localized locale on GitLab's documentation site. The merge request merged on schedule on 10 December 2025.
• The language selector preserves your place in the page, so switching language is a navigation action rather than a restart — a small fix with a disproportionate effect on whether the localized docs feel usable or merely present.
• A repeatable path for German and French. The Hugo multilingual configuration, the selector behaviour, the /help handoff and the QA routine are all language-agnostic now. The next locale is a content problem, not an infrastructure problem — which was the actual point of doing the first one carefully.
• A documented launch pattern: deployment, monitoring and announcement as three separately owned tracks with a fixed cutover time in the reader's timezone.