Localization

Use localization when you want readers to switch languages without leaving the same docs project.

Keep the default language at the root. Add one folder for each translated language.

Project Structure

Use the root pages for your default language. Mirror the same page names in each locale folder.

Enable The Language Switcher

Add languages under navigation:

{
  "navigation": {
    "languages": {
      "default": "en",
      "items": ["en", "fr", "nl", "jp"]
    },
    "tabs": [
      {
        "id": "docs",
        "label": {
          "en": "Docs",
          "fr": "Documentation",
          "nl": "Documentatie",
          "jp": "ドキュメント"
        },
        "content": ["index", "getting-started", "cli"]
      }
    ]
  }
}

Translate Navigation Labels

Translate every label and title that appears in navigation.

{
  "title": {
    "en": "Getting Started",
    "fr": "Bien demarrer",
    "nl": "Aan de slag",
    "jp": "はじめに"
  }
}

Show Pages Only In Some Languages

Use the languages field when a page or group should only appear in some languages.

{
  "page": "enterprise-rollout",
  "title": {
    "en": "Enterprise Rollout",
    "fr": "Deploiement entreprise"
  },
  "languages": ["en", "fr"]
}

Writing Tips

• Keep page names the same across languages.

• Translate navigation labels and page titles, not just body text.

• Start with your most important pages.

• Use code groups for programming languages and locale folders for human languages.

A Good Rollout Plan

1. Publish the full docs set in English.

2. Translate the homepage, CLI guide, and getting-started path into one additional language.

3. Add translated navigation labels.

4. Translate deeper guides after you know which pages people use most.

Next Pages