Today we are thrilled to announce the release of GitLab product documentation in Japanese at docs.gitlab.com/ja-jp. This major step marks our first move toward making GitLab’s extensive documentation accessible to our users worldwide.

The unique challenge of the Japanese market

Japan represents one of the world’s largest economies and is a critical market for enterprise software. However, it also presents a distinctive challenge: despite its technological sophistication and massive developer community, English proficiency remains a significant barrier for many users.

Japan’s developers and DevSecOps teams often face challenges with English-only documentation, as indicated by the country’s ranking on the EF English Proficiency Index. This language barrier can significantly impact the speed of learning and ultimately influence the decision to evaluate, adopt, and champion a platform within Japanese organizations.

We’ve heard directly from our Japanese customers and partners that English-only documentation wasn’t merely an inconvenience, it was a barrier preventing them from getting the most out of GitLab. The impact rippled through every stage of the user journey: From initial evaluation where teams struggled to assess GitLab’s capabilities, to daily operations where finding solutions took longer than necessary, to staying current with new features and best practices.

In a market as competitive and mature as in Japan, this language barrier directly affected GitLab’s market penetration. When Japanese companies evaluate enterprise software, the availability of comprehensive Japanese documentation signals long-term commitment to the market. It demonstrates that a provider isn’t just making a token effort, but is genuinely invested in supporting Japanese users throughout their entire journey.

To address this challenge and demonstrate our commitment to the Japanese market, we built localization infrastructure from the ground up, integrating with how we create and maintain documentation at GitLab.

Localization built on docs-as-code principles

GitLab’s documentation is treated like any other code contribution, residing alongside product code in GitLab projects and managed via merge requests. This system ensures documentation is version-controlled, collaboratively reviewed, and automatically tested through CI/CD pipelines, which includes checks for issues with language, formatting, and links. Both the English and Japanese documentation sites are dynamically generated using the Hugo static site generator and deployed after merging changes, guaranteeing users always access the latest information.

The documentation is extensive and comprehensive, drawing content from various source projects, including GitLab, GitLab Runner, Omnibus GitLab, GitLab Charts, GitLab Operator, and GitLab CLI (glab) (see architecture for details). This sheer scale and rapid update velocity presented a significant localization challenge. To keep pace with the continuous evolution of these source English projects, we had to design a localization infrastructure for our GitLab product documentation that could handle these unique complexities and provide an enterprise-grade solution for a fully localized site, all while adhering to our CI/CD pipeline requirements.

How we localized GitLab Documentation

For our initial Japanese localization, we adopted a strategy of integrating new folders within our existing English content structure. Specifically, we introduced doc-locale/ja-jp folders within each project that stores source Markdown files. This architecture keeps the translations right alongside their source content while maintaining a clear organizational separation. Not only that, but it also enables us to apply the same robust version control, established review and collaboration workflows, and even some of the automated quality checks used for our English documentation to the translated content.

This internationalization infrastructure built for Japanese documentation provides a scalable foundation for future language expansion. With the architecture, tooling, and processes now in place, we are well-positioned to support additional languages as we continue our commitment to making GitLab accessible to users worldwide.

An AI-assisted translation workflow that balances speed and quality

We adopted a strategic, phased approach to processing the content through translation, prioritizing pages based on their English-language page views. The highest-traffic pages underwent AI translation first, followed by comprehensive human linguistic review, and we intentionally paused subsequent phases until these priority pages completed the full human review cycle. This deliberate sequencing allowed us to build a robust, curated translation memory and termbase from our most important content. These linguistic assets accelerated and improved quality across all remaining content. In parallel, this initial phase served as our testing ground on the technical infrastructure on the GitLab side. We used it to iterate and reinforce our CI/CD pipelines, refine our translation and post-editing AI scripts, and solidify our Translation MR review process.

To provide our international users with the most current documentation while guaranteeing high-quality translated content, we implemented an AI-assisted translation workflow with human post-editing, consisting of:

• Phase 1: AI-powered translation. We built a custom AI translation system enriched with GitLab-specific context including style guides, GitLab UI content translations, terminology databases, and original file context. This system intelligently handles GitLab’s specialized markdown syntax (GLFM) and protects elements like placeholder variables, alert boxes, Hugo shortcodes, and GitLab-specific references that standard translation tools can’t process out of the box.
• Phase 2: Human linguistic review. Professional Japanese translators specialized in technical content then review and refine the AI translations. They work with GitLab’s Japanese style guide, translation memory, and terminology database to ensure accuracy, natural language flow, and cultural appropriateness. These human-reviewed translations progressively replace the AI versions on the site.

Technical challenges and solutions

Localizing GitLab’s extensive documentation, while maintaining our docs-as-code principles and CI/CD-driven publishing workflow, required significant technical innovation. The challenges extended beyond translation itself: we needed to preserve complex markdown syntax, maintain automated testing standards, ensure seamless content fallbacks, and create sustainable processes for continuous updates across multiple source projects.

The English markdown file syntax complexity led us to developing custom code and regex in our Translation Management System (TMS) to protect codeblocks, URLs, and other functional elements that should not be exposed for translation.

Due to the dynamics of how the English content is generated, we established an English fallback mechanism. Essentially, when the Japanese translation is not ready yet, the localized site seamlessly displays English content with translated navigation and UI, preventing 404s and maintaining language context via Hugo’s rendering system.

We enhanced the localized navigation and linking so that it adjusts dynamically and would persist the locale. We added anchor IDs in the translated files by pre-processing the English file before it’s sent for translation. That improves the experience for people navigating to a docs page from a link. The consistent anchor ID means they can change to either language and still land in the correct place in the page.

We also extended CI/CD pipelines to test localized content in Translation MRs following the same quality standards as the English docs. It allows us to catch invalid Hugo shortcodes, spaces inside links, or bare URLs. It also identifies orphaned files and redirects files with no target files. You can see the jobs that run on the MRs containing translated documentation on the GitLab project .gitlab/ci/docs.gitlab-ci.yml file.

A centralized translation request system orchestrates the workflow, monitors the English files, identifies new and updated content, routes files for translation, automatically creates translation merge requests, tracks file status in translation requests and maintains an audit trail. To get docs translated we processed 430 Translation MRs with files ranging from 1-10 in each Translation MR.

The result is a Japanese documentation experience that stays synchronized with English content updates, giving users faster access to critical information. Users can discover and navigate content fully in their language, with English appearing only for content that’s still in translation. They can trust GitLab’s quality standards while accessing the latest features quickly. All of this creates a sustainable, scalable foundation for future languages and documentation growth.

Learn more about all the technical details in our GitLab Product Documentation Handbook page.

Visit our Japanese docs site

Whether you’re a longtime GitLab user or just getting started, we hope this localized documentation makes your DevSecOps journey smoother and more accessible.

This is just the beginning of our localization efforts, and your feedback is invaluable in helping us improve. If you notice any translation issues, have suggestions for improvement, or simply want to share your experience using the Japanese documentation, please don’t hesitate to reach out. You can provide comments in our feedback issue.

As we continue evolving this localization infrastructure, our immediate priorities include enhancing the search experience for Japanese users, and accelerating our continuous localization workflow to minimize the time gap between English updates and their Japanese translations. Thank you to our Japanese community for your continued support and patience as we work to serve you better. We’re committed to making GitLab the best DevSecOps platform for Japanese teams, and comprehensive Japanese documentation is a crucial step in that journey.

Start exploring today at docs.gitlab.com/ja-jp!