Localization in Docs-as-Code — Complete Guide

Localization adapts documentation for international audiences. Learn how to localize docs-as-code projects using translation management systems, automated translation pipelines, and multilingual static site configuration.

What You'll Learn

You will learn how to structure documentation for translation, configure multilingual sites, manage translation workflows in Git, and automate localization in your pipeline.

Why It Matters

English-only documentation excludes a majority of the world's developers. International audiences prefer documentation in their native language. Localization expands your user base and improves developer experience globally.

Real-World Use

DodaTech documentation is available in English, Spanish, and Japanese. Each language has its own content directory in the Repository, and translations are managed through Crowdin with automated PR creation.

flowchart LR
  A[English Source Docs] --> B[Translation Management]
  B --> C[Community Translations]
  B --> D[Professional Translations]
  C --> E[Translation PR]
  D --> E
  E --> F[Review and Approve]
  F --> G[Build Multilingual Site]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Folder Structure for Multilingual Docs

content/
  en/
    getting-started/
      _index.md
      installation.md
    api/
      reference.md
  es/
    getting-started/
      _index.md
      installation.md
    api/
      reference.md
  ja/
    getting-started/
      _index.md
      installation.md
    api/
      reference.md

Configuring Multilingual Hugo

# hugo.yaml
defaultContentLanguage: en
languages:
  en:
    languageName: English
    weight: 1
    params:
      description: "Official documentation"
  es:
    languageName: Espanol
    weight: 2
    params:
      description: "Documentacion oficial"
  ja:
    languageName: Nihongo
    weight: 3
    params:
      description: "Koshiki dokumenteshon"

Translation Management with Git

Store translations in the same repository as source content:

# Source content in English
content/en/getting-started/installation.md

# Translation in Spanish
content/es/getting-started/installation.md

Use a translation management system to sync translations:

# Push source to Crowdin
crowdin upload sources

# Download translations
crowdin download

# The translations are placed in the correct directories
# and can be committed as a PR
git add content/es/ content/ja/
git commit -m "i18n: update Spanish and Japanese translations"

Automated Translation Pipeline

# .github/workflows/translation.yml
name: Translation Sync
on:
  schedule:
    - cron: "0 0 * * 1"  # Weekly
  workflow_dispatch:
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Upload sources
        uses: crowdin/github-action@v1
        with:
          upload_sources: true
          upload_translations: false
          download_translations: true
          crowdin_branch_name: main
          config: crowdin.yml
      - name: Create PR
        uses: peter-evans/create-pull-request@v5
        with:
          title: "i18n: update translations"
          body: "Automated translation update"

Localizing UI Strings

# i18n/en.yaml
search:
  placeholder: Search documentation
  no_results: No results found
  results: Results

# i18n/es.yaml
search:
  placeholder: Buscar documentacion
  no_results: No se encontraron resultados
  results: Resultados

Common Mistakes

1. Hardcoding Text in Templates

UI strings in templates must use i18n keys, not hardcoded text. Hardcoded text requires template changes for each language.

2. Not Accounting for Text Expansion

Translated text can be 30 percent longer than English. Design layouts that accommodate variable text lengths.

3. Ignoring Right-to-Left Languages

Arabic, Hebrew, and other RTL languages need CSS direction support. Test the layout with RTL content.

4. Translating Code Examples

Code examples should not be translated. Only translate surrounding text, comments, and documentation.

5. No Translation Review Process

Machine translations need human review. Automated translations without review introduce errors.

Practice Questions

1. What is the difference between translation and localization?

Translation converts text from one language to another. Localization adapts content for a specific locale, including date formats, currency, and cultural references.

2. How do you structure a multilingual documentation repository?

Each language has its own content directory (content/en, content/es). UI strings are stored in i18n files.

3. Why should code examples not be translated?

Code examples must remain in their original programming language. Translating variable names or function names breaks the code.

4. What is the role of a translation management system in docs-as-code?

It bridges the gap between source content and translations, managing translation memory, glossary, and workflow while keeping translations in the Git repository.

5. Challenge: Set up a multilingual Hugo site with English and one other language. Create sample content in both languages, configure the language switcher, and add localized UI strings.

FAQ

Mini Project

Create a multilingual documentation project with English and Spanish content. Set up the folder structure, configure Hugo or Docusaurus for two languages, create translated pages, add a language switcher to the navigation, and set up a translation management workflow.

What's Next

With localization set up, learn about Analytics for Docs to measure how users interact with your documentation. Then complete the Docs-as-Code Project.