TechPrufer
Get started
GitLab
GitLab logoGitLab · Feature trail

Documentation Localization Infrastructure

5 posts · Jul 2016 – Dec 2025

What this trail covers

GitLab is evolving its approach to documentation management by adopting a comprehensive 'docs-as-code' workflow. This involves using GitLab itself for planning, creating, reviewing, editing, and publishing documentation. The process leverages GitLab issues and issue boards for planning, merge requests for collaborative feedback and review, and a review app feature for previewing changes. Automated testing is integrated into the CI/CD pipeline to ensure content quality, and the final HTML output is dynamically generated using Hugo. This infrastructure is now being extended to support localization, starting with Japanese, by integrating new folders within the existing English content structure (`doc-locale/ja-jp`). This architecture keeps translations alongside source content, enabling version control, collaborative review, and automated quality checks. An AI-assisted translation workflow with human post-editing is employed, balancing speed and quality. Technical challenges include preserving complex markdown syntax, establishing English fallback mechanisms, dynamically adjusting navigation and linking with anchor IDs, and extending CI/CD pipelines for localized content testing. A centralized translation request system orchestrates the workflow, monitors English files, routes for translation, and creates translation merge requests. Future priorities include enhancing search experience for localized users and accelerating the continuous localization workflow.

All GitLab trails
  1. How we built and automated our new Japanese GitLab Docs siteThis post details the implementation of a new localization infrastructure for GitLab's product documentation, specifically for Japanese. It describes the adoption of 'docs-as-code' principles for translated content, including placing `doc-locale/ja-jp` folders alongside source Markdown files. The post outlines an AI-assisted translation workflow with human post-editing, the technical challenges of preserving markdown syntax, implementing English fallback mechanisms, and dynamically adjusting navigation with anchor IDs. It also highlights the extension of CI/CD pipelines to test localized content and the use of a centralized translation request system to orchestrate the workflow. The goal is to keep localized documentation synchronized with English updates and provide a scalable foundation for future language expansion.
  2. Five fast facts about docs as code at GitLabThis post details the practical application of GitLab's features for a 'docs-as-code' workflow. It highlights the use of GitLab issues and boards for planning, merge requests for collaborative content review and editing with suggestions, a review app for previewing documentation changes, CI/CD pipelines for automated testing (link checking, spelling, grammar), and GitLab Pages for hosting the generated HTML output. It emphasizes the benefits of a single platform for the entire documentation lifecycle.
  3. How to automate localization for Flutter appsThis post introduces an automated localization workflow for Flutter apps by integrating GitLab with the Localizely platform. It details the steps to set up a `localizely.yml` configuration file, establish GitLab integration on Localizely, and configure a webhook in the GitLab repository. This automation streamlines the process of synchronizing ARB translation files between GitLab and Localizely, reducing manual effort and improving efficiency for developers and translators.
  4. How Weet integrates localization into the GitLab pipeline with LokaliseThis post details how Weet integrated Lokalise with GitLab CI/CD to automate their localization workflow. Key technical contributions include: 1. Automating the extraction of text strings from the codebase into Lokalise upon each push to master. 2. Utilizing Lokalise's task features to assign translation work to the marketing team. 3. Creating merge requests from Lokalise for translated content, integrating it back into the development pipeline. 4. Implementing internal processes for managing localization data, including splitting it into multiple .json files based on component (emails, frontend, integration, server-side rendering, mobile), using a naming pattern for simplified key maintenance, and establishing rules for conflict resolution (developers only update labels in Lokalise, add/remove keys locally). This enables continuous localization within an hour for new releases.
  5. An Agile approach to documentation and structureThis post details the author's personal approach to organizing project documentation and assets for a new app, 'UnscrewMe'. The author leverages GitLab for its private repositories, Markdown rendering, and project management features (issues, milestones, issue boards) to structure their work. They define a flexible folder structure ('ideas', 'concepts', 'business', 'roadmap', 'design', 'finance') and use dated file naming conventions. Google Keep is used for quick, offline content generation, and Visual Studio Code is used for editing and committing Markdown files to Git, referencing GitLab issues in commit messages.
  7. Building a new GitLab Docs site with Nanoc, GitLab CI, and GitLab PagesThis post details the technical implementation of a new documentation site for GitLab.com. It describes the choice of Nanoc as a static site generator, the build process involving cloning multiple repositories (CE, EE, Omnibus, Runner) and merging their documentation directories, and the use of Rake tasks for automation. It also explains the integration with GitLab CI for testing (link validation, compilation) and deployment via GitLab Pages. The post highlights the requirements for handling documentation from multiple repositories and the future need for versioning.
  8. Markdown Kramdown Tips and TricksThis post details specific Kramdown syntax for applying CSS classes, custom IDs, and custom attributes to HTML elements within Markdown. It explains how to generate tables of contents (ToC) automatically, including excluding specific headings. The post also covers embedding HTML blocks, such as iframes for videos and documents, and using Font Awesome icons. It introduces the `{::options parse_block_html="true" /}` directive to mix HTML with Markdown and demonstrates how to include `<style>` tags directly within Markdown files for localized styling. The post references the GitLab Handbook's Markdown Guide for further details and encourages community contributions.