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/

Branch structure

Overview

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.
3. main-development This is our development workspace for i18n features.
4. live-preview A stable live preview branch for the internationalized GitLab documentation. See MR for more details.

Branch maintenance

How to Update Localization Forks with Upstream Changes**

Steps

1. Update the fork’s main branch
   • Update your fork’s default branch (main or master) to match the production project’s default branch
   • Use the “Update Fork” button in the UI
2. Create a merge request (MR)
   • Create an MR that merges the default branch to main-translation
   • This MR will contain all documentation changes since the last update
3. Review changed files
   • Pipelines: If pipelines fail, this is typically due to upstream configuration issues
     • In most cases, you can force the merge and ignore pipeline issues
     • Attempting to fix these issues often consumes engineering resources unnecessarily
   • Merge conflicts: Review these case by case
     • May need to be relayed to the localization team
     • Conflicts occur because of upstream changes
     • Ignoring conflicts on target files will cause future translations to overwrite upstream changes
4. Merge the MR to main-translation
   • This updates the translation branch with the default branch
   • Triggers Argo-GitLab integration to check for source language file updates

See example MR for updating the main-translation branch with content from the Omnibus Production fork.

i18n Development Environments

Main Development Branch

The main-development branch is our dedicated environment for i18n feature development. It builds localized routes and enables review apps using translations from production forks’ main-translation branches. This merge request documents the changes to enable i18n feature development.

Working with the i18n environment

1. Always create feature branches from main-development
2. Target merge requests to main-development
3. Test with translations from all projects’ main-translation branches
4. After approval, open a separate MR to contribute upstream

It is helpful to set up a dedicated directory on your machine for this environment, since it also requires external projects from our production fork, specically the main-translation branch.

cd htdocs
mkdir main-devevelopment
git clone git@gitlab.com:gitlab-com/localization/tech-docs-forked-projects/test/gitlab-docs.git
cd gitlab-docs
mise trust
make setup
USE_SSH=true make clone-docs-projects

Your resulting directory structure should look like this:

main-development
├── charts-gitlab/ (main-translation)
├── gitlab/ (main-translation)
├── gitlab-docs/ (main-development)
├── gitlab-runner/ (main-translation)
├── gitlab-operator/ (main-translation)
└── omnibus-gitlab/ (main-translation)

Refer to documentation here for setting up your workstation further: https://gitlab.com/gitlab-com/localization/tech-docs-forked-projects/test/gitlab-docs/-/blob/main/doc/setup.md?ref_type=heads#set-up-your-workstation

Updating main-development

• Use the “Update fork” button at our forked repository
• If conflicts occur, update locally:

cd /htdocs/localization/main-development/gitlab-docs ## cd into your gitlab-docs directory using the main-development branch
git fetch
git checkout main-development
git merge origin/main
git push origin main-development 

Review App

The review app enables our team to review internationalized documentation and features before production deployment. It consolidates translated content from all five repositories (GitLab, Operator, Omnibus, Runner, Charts), maintains production-identical build pipelines, and utilizes the i18n features built for Hugo.

While the latest main-development branch contents are visible, it won’t automatically update when there are changes to the main-translation forks. Run a new pipeline to pull those in.

First visit https://gitlab-docs-hugo-19c275.gitlab.io/ to oauth yourself to the server, then visit https://gitlab-docs-hugo-19c275.gitlab.io/review-mr-27/ to see the latest main-development branch contents.

This implementation follows the architecture detailed in tech-docs-forked-projects/test/gitlab-docs/-/merge_requests/27.

View page source - Edit this page - please contribute.