Localization Tools for Documentation — Complete Guide

In this tutorial, you will learn about Localization Tools for Documentation. We cover key concepts, practical examples, and best practices to help you master this topic.

Localization tools manage the translation workflow for documentation projects. Compare Crowdin, Lokalise, and Transifex for managing translations, translation memory, and integration with docs-as-code pipelines.

What You'll Learn

You will learn how to choose localization tools, how to integrate them with your docs-as-code workflow, and how to manage translations efficiently.

Why It Matters

Reaching global audiences requires documentation in multiple languages. Localization tools streamline the translation Process, manage translation memory, and keep translations in sync with source content.

Real-World Use

DodaTech uses Crowdin for managing translations. Source content in English is pushed to Crowdin, community translators contribute, and translations are pulled back into the Repository as PRs.

flowchart LR
  A[Source Docs (English)] --> B[Push to Crowdin]
  B --> C[Translators Work]
  C --> D[Pull Translations]
  D --> E[Create PR]
  E --> F[Review and Merge]
  F --> G[Build Multilingual Site]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Tool Comparison

Crowdin Configuration

# crowdin.yml
project_id: "12345"
api_token: "YOUR_API_TOKEN"
base_path: "."

files:
  - source: /content/en/**/*.md
    translation: /content/%two_letters_code%/**/%original_file_name%
    languages_mapping:
      two_letters_code:
        es: es
        ja: ja
        fr: fr

# Push source files to Crowdin
crowdin upload sources

# Download translations
crowdin download

Lokalise Integration

# Install Lokalise CLI
npm install -g @lokalise/node-api

# Upload source files
lokalise2 file upload \
  --token YOUR_API_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --file content/en/getting-started/installation.md \
  --lang-iso en

# Download translations
lokalise2 file download \
  --token YOUR_API_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --format markdown \
  --dest content/

Translation Memory Benefits

Translation memory stores previously translated segments:

# Translation memory match example
Source: "Click the Save button to save your changes."
Translation (existing): "Haga clic en el boton Guardar para guardar los cambios."

New source: "Click the Save button to save your settings."
Match: 90% (only "changes" changed to "settings")
Suggestion: "Haga clic en el boton Guardar para guardar su configuracion."

Automated Translation Workflow

# .github/workflows/localization.yml
name: Localization Sync
on:
  push:
    branches: [main]
    paths:
      - 'content/en/**'
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Upload sources to Crowdin
        uses: crowdin/github-action@v1
        with:
          upload_sources: true
          crowdin_branch_name: main
      - name: Download translations
        uses: crowdin/github-action@v1
        with:
          download_translations: true
          create_pr: true

Common Mistakes

1. Translating Code Examples

Code blocks must remain in their original form. Translate only the surrounding documentation text.

2. Not Using Translation Memory

Without translation memory, the same phrase gets translated differently each time, creating inconsistency.

3. Ignoring Screenshots

Screenshots with text need separate localized versions or should use text-free designs.

4. Relying Only on Machine Translation

Machine translation needs human review. Publish machine-translated content only after human editing.

5. No Quality Assurance Workflow

Translations need review. Set up a translation QA process with native speakers.

Practice Questions

1. What is translation memory and why is it important?

Translation memory stores previously translated segments and reuses them, ensuring consistency and reducing translation cost.

2. How does Crowdin integrate with a Git-based documentation workflow?

Crowdin syncs with Git by pushing source files for translation and creating PRs for completed translations.

3. Why should code examples not be translated?

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

4. What is the role of machine translation in documentation localization?

Machine translation provides initial drafts that human translators then review and refine, reducing translation time.

5. Challenge: Set up a Crowdin project for a documentation repository. Push source files, configure language mapping for Spanish and Japanese, and set up an automated workflow that downloads translations.

FAQ

Mini Project

Set up a Crowdin project for a sample documentation repository with English source files. Configure Spanish as a target language. Push source files, simulate a translation, download the translation, and integrate it into a Hugo multilingual build.

What's Next

After localization, explore Analytics Tools like Plausible and Fathom for tracking documentation usage. Then learn about Search Tools.