How to set up multi-language documentation - Mintlify

Internationalization (i18n)

Internationalization (i18n) is the process of designing software or content to work for different languages and locales. This guide explains how to structure files, configure navigation, and maintain translations effectively so that you can help users access your documentation in their preferred language and improve global reach.

File structure

Organize translated content in language-specific directories to keep your documentation maintainable and structure your navigation by language. Create a separate directory for each language using ISO 639-1 language codes. Place translated files in these directories with the same structure as your default language.

Supported language codes

• ar - Arabic
• ca - Catalan
• zh or zh-Hans or zh-CN - Chinese (Simplified)
• zh-Hant or zh-TW - Chinese (Traditional)
• cs - Czech
• da - Danish
• de - German
• en - English
• es - Spanish
• fi - Finnish
• fr - French
• fr-CA - French (Canadian)
• he - Hebrew
• hi - Hindi
• hu - Hungarian
• id - Indonesian
• it - Italian
• ja or ja-JP - Japanese
• ko - Korean
• lv - Latvian
• nl - Dutch
• no - Norwegian
• pl - Polish
• pt or pt-BR - Portuguese
• ro - Romanian
• ru - Russian
• sv - Swedish
• tr - Turkish
• uk - Ukrainian
• uz - Uzbek
• vi - Vietnamese

Example file structure

docs/
├── index.mdx                    # English (default)
├── quickstart.mdx
├── fr/
│   ├── index.mdx               # French
│   ├── quickstart.mdx
├── es/
│   ├── index.mdx               # Spanish
│   ├── quickstart.mdx
└── zh/
    ├── index.mdx               # Chinese
    └── quickstart.mdx

Keep the same filenames and directory structure across all languages. This makes it easier to maintain translations and identify missing content.

Configure the language switcher

To add a language switcher to your documentation, configure the languages array in your docs.json navigation.

docs.json

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["index", "quickstart"]
          }
        ]
      },
      {
        "language": "es",
        "groups": [
          {
            "group": "Comenzando",
            "pages": ["es/index", "es/quickstart"]
          }
        ]
      }
    ]
  }
}

Each language entry in the languages array requires:

• language: ISO 639-1 language code
• Full navigation structure
• Paths to translated files

The navigation structure can differ between languages to accommodate language-specific content needs.

Do not use the same page path in more than one language to avoid undefined behavior.

Set default language

Mintlify uses the first language in the languages array as the default. To use a different language as the default, reorder the array or add the default property:

docs.json

{
  "navigation": {
    "languages": [
      {
        "language": "es",
        "groups": [...] // Configure as needed
      },
      {
        "language": "en",
        "groups": [...] // Configure as needed
      }
    ]
  }
}

Alternatively, use the default property:

docs.json

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [...] // Configure as needed
      },
      {
        "language": "es",
        "default": true,
        "groups": [...] // Configure as needed
      }
    ]
  }
}

Single language documentation

If you only want one language available without a language switcher, remove the languages field:

docs.json

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["index", "quickstart"]
          }
        ]
      }
    ]
  }
}

Translate navigation labels to match the content's language for a fully localized experience.

Maintain translations

Keep translations accurate and synchronized with your source content.

Translation workflow

1. Update source content in your primary language.
2. Identify changed content.
3. Translate changed content.
4. Review translations for accuracy.
5. Update translated files.
6. Verify navigation and links work.

Images and media

Store translated images in language-specific directories.

images/
├── dashboard.png          # English version
├── fr/
│   └── dashboard.png     # French version
└── es/
    └── dashboard.png     # Spanish version

Reference images with relative paths in your translated content:

es/index.mdx

SEO for multi-language sites

Optimize each language version for search engines using translated metadata in each file's frontmatter:

fr/index.mdx
---
title: "Commencer"
description: "Apprenez à commencer avec notre produit."
keywords: ["démarrage", "tutoriel", "guide"]
---

Best practices

Date and number formats

Consider locale-specific formatting for dates and numbers:

• Date formats: MM/DD/YYYY vs DD/MM/YYYY
• Number formats: 1,000.00 vs 1.000,00
• Currency symbols: $100.00 vs 100,00€

Maintain consistency

Maintain content parity across all languages to ensure quality.

Layout differences

Some languages may require different spacing. Test translated content on various screen sizes to ensure:

• Navigation fits properly.
• Code blocks are readable.
• Tables and formatted text remain clear.

Character encoding

Ensure your environment supports UTF-8 encoding to display characters correctly.

Frequently asked questions

1. Do I need to translate every page before launching a new language?
   • No, you can launch with partial coverage.
2. What happens when a translated page is missing?
   • You’ll see a 404; maintain parity between languages.
3. Should navigation labels be translated?
   • Yes, they should match the content's language.
4. How do I handle code examples in translated content?
   • Do not translate code itself, but translate comments to explain concepts.