Localization Engineering

Technical overview of GitLab’s localization infrastructure and engineering processes across documentation and product interfaces. Includes translation environments, branch management, development workflows, and preview systems for internationalized content.

Iteration Process

We start our iteration on a Tuesday. We release throughout the iteration. Iterations are 2 weeks long.

See our Localization engineering iterations here.

Labels and Workflow Boards

We use issue boards to track issue progress throughout an iteration. Issue boards should be viewed at the highest group level for visibility into all nested projects in a group.

The Localization team uses the following issue labels for distinguishing which part of the org the work belongs to and distinguishing between specialities:

The Localization team uses the following scope labels to categorize documentation engineering work.

Iteration Board #9140637

Board: https://gitlab.com/groups/gitlab-com/localization/-/boards/9140637

Displays all issues with ~“L10n::engineering” label assigned to current Localization engineering iterations

Docs Engineering (Stream) Boards #7828627

Board: https://gitlab.com/groups/gitlab-com/localization/-/boards/7828627

Tracks all documentation-related engineering tasks in the Localization project. This board displays all issues with both ~“L10n-docs” and ~“L10n::engineering” labels.

Internationalized Documentation - docs.gitlab.com

The GitLab docs site is beeing enabled for internationalization, with initial support for Japanese translations. https://docs.gitlab.com/ja-jp/

Translation content sources

Translated content for https://docs.gitlab.com is pulled from separate /doc-locale/ directories in the following repositories:

• GitLab
• Operator
• Omnibus
• Runner
• Charts

Translation environments

We maintain two separate environments that contain all projects used to compile docs.gitlab.com. These contain forks of the upstream projects.

Production environment: localization/tech-docs-forked-projects/prod/

Test environment: localization/tech-docs-forked-projects/test/

Each project within these environments maintains the following branch structure:

1. main Used exclusively for pulling upstream changes into our fork. Do not contribute to this branch.
2. main-translation Used for delivering translations from our Translation Management System (TMS). Do not contribute to this branch.

Translation Preview

Our production fork of the docs-gitlab-com project includes a dedicated branch for internationalization development:

main-development – Our i18n feature development environment that:

• Builds localized documentation routes
• Enables review apps using translations from production forks’ main-translation branches
• Allows the team to review translations before upstream deployment

The setup is documented in this merge request: https://gitlab.com/gitlab-com/localization/tech-docs-forked-projects/prod/gitlab-docs/-/merge_requests/31

The review app provides a comprehensive testing environment that:

• Consolidates translated content from all five documentation repositories (GitLab, Operator, Omnibus, Runner, Charts)
• Maintains production-identical build pipelines
• Leverages Hugo’s built-in i18n features
• Enables pre-production review of internationalized documentation and feature development

Note: The preview doesn’t automatically sync with main-translation fork updates. To incorporate the latest translation changes, manually trigger a new pipeline.

Enabling i18n in Production

The i18n features are now deployed to production. To toggle the translated site:

1. Edit config/_default/hugo.yaml
2. Change the language setting:

languages.ja-jp.disabled: false

This single configuration change activates/deactivates the entire translated documentation site.

Review workflow

The process of reviewing merge requests by the Localization Engineering team aligns with the GitLab Code Review Guidelines.

Localization Engineering team reviews each other’s merge requests and Translation MRs. Translation MRs are created by @gitlab-argo-bot when translations are complete in Argo for the Marketing website and GitLab product documentation.

Localization Engineering helps review MRs that are authored in Decap CMS by the Localization Content Managers who own and maintain Blog in multiple languages. Blog update MRs from Decap are typically content-only changes that help with deployment agility and can use lightweight review processes. Content Managers may request a review from a Localization Engineer or a Digital Experience (DEX) engineer for complex changes, code, or troubleshooting.

Review of GitLab product documentation Translation MRs

Work in progress guidelines

Syncing product documentation forks with upstream projects

We have automated the content syncing between upstream product documentation projects and downstream forks using Automate tech docs fork project.

Two independent processes handle this:

Part One: Mirroring process (upstream sync)

First part of the process is to sync between master/main branches of the downstream forks to the upstream projects master/main branches. This process is called Mirroring and it gets done using GitLab’s internal Pull Mirroring API. The mirroring process is not bidirectional, meaning it only mirrors every change from upstream to downstream. There’s a minimum of 5-minute interval:

1. GitLab first adds the mirrored repository to a queue
2. Once per minute, a Sidekiq cron job schedules mirrors for updates based on available capacity
3. If an update succeeds, the execution is re-queued with at least a 30-minute wait
4. If the mirroring fails, it retries later. However, after 14 consecutive failures, it stops automatically and needs manual intervention. See the troubleshooting ideas below.

Part Two: Pipeline sync process (translation branch sync)

Once master/main branches are in sync with upstream projects, another mechanism follows inside each of the downstream forks. The goal of this step is to run a pipeline sync that merges the changes from respective master/main branch of each of the downstream forks to it’s main-translation branch. This process runs completely independent of the pull mirroring at 12-hour interval and this only brings changes from master/main down to main-translation branches, making it one directional. This makes the Automate Tech Docs fork pipeline sync within the fork repository itself with no direct connection to the upstream projects. This design decision is to ensure we do not have any direct interdependency (e.g., adding a bot as a member or creating access tokens) to any of the upstream projects.

Troubleshooting Ideas

Despite having some fail-safe measures built into the pipeline, we may encounter errors. Here’s some common troubleshooting techniques:

Mirroring failed

If you receive error messages like Pull mirroring failed xx minute(s) ago, then here’s what needs to be verified:

1. Check the error message by going into the Mirroring settings (“Maintainer” level access is required). Hover over on the “Error” button to view the error log
2. If the error is somewhere along the lines of fatal: unable to access ... or Token was revoked ..., you may have an issue with the project access token. To resolve this, go to the “Access tokens” under “Settings” and re-verify the validity of the token.
3. However, if the error message says ... You are not allowed to push code to protected branches on this project, then make sure the user (associated with the access token) has Push or Merge rights to the master/main branch.
4. The error messages can also be debugged using the GitLab’s internal Pull Mirroring API.

Automated Tech Docs Fork Pipeline failed

1. If the error is due to access issues (similar to the ones above), check the associated CI/CD variables for the relevant access token and update if necessary.
2. If the pipeline is failed due merge conflicts, consider fixing the conflicts for the respective project.

#Localization-alerts Slack channel

We’ve created a public #localization-alerts channel where users can subscribe to receive up-to-date information about failures for this pipeline sync. Since this pipeline runs every hour, the channel is designed to only receive failure reports.

Localization engineering by partnership with Spartan Software

The Localization team partners with Spartan Software, Inc. to develop and maintain the localization request management system and a suite of microservices and integrations. Spartan Software engineers and architects provide specialized expertise in language technology platforms and integrations.

The suite of various integrations, components and microservcies is referred to by the overarching term of Argo. See high level architecture here, and the GitLab-specific architecture here.

Engineering labels and workflow related to Argo

We use the following scoped labels to track Argo engineering work performed by Spartan Software:

Argo system components

Argo serves as GitLab’s centralized localization technology and management infrastructure, encompassing:

• Request Management System: centralized intake and tracking of localization requests across all GitLab content types, both manual or automatic through integrations
• Translation Management System integrations: automated connections between GitLab systems and commercial TMS platforms (Phrase, TranslationOS, Contentful, etc.)
• Argo GitLab Agent: a purpose-built microservice / component of the Argo ecosystem for specialized localization-related tasks, such as translatable file pre- / post-processing, etc.
• Argo-GitLab Integration aka GitLab Translation Service: direct integrations with GitLab projects, merge request workflows, and CI/CD pipelines

Argo engineering board

The Argo Development board displays all issues with Argo-Engineering labels and provides visibility into:

• Current development work in progress by Spartan Software
• Completed enhancements ready for deployment by using relevant milestones
• Planned Argo system improvements and integrations

Communication channels

#spartan-software: Direct Slack communication channel with Spartan Software engineering team

Technical coordination occurs through GitLab issues tagged with appropriate Argo-Engineering labels

This partnership enables the Localization team to maintain sophisticated translation infrastructure while focusing internal engineering team on core localizability, feature development and enhancements for marketing website, GitLab product documentation, and GitLab product.

View page source - Edit this page - please contribute.