Skip to main content
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.
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 file names 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.
Translate navigation labels like group or tab names to match the language of the content. This creates a fully localized experience for your users.
To add global navigation elements that appear across all languages, configure the global object in your docs.json navigation.
docs.json
{
  "navigation": {
    "global": {
      "anchors": [
        {
          "anchor": "Documentation",
          "href": "https://example.com/docs"
        },
        {
          "anchor": "Blog",
          "href": "https://example.com/blog"
        }
      ]
    },
    "languages": [
      // Language-specific navigation
    ]
  }
}

​
External URLs for language switcher

For multi-domain documentation setups where different locales are hosted on separate domains, you can configure external URLs in the language switcher. This is useful when not all pages exist in all locales or when you maintain separate documentation sites per region. Configure default external URLs in your docs.json:
docs.json
{
  "navigation": {
    "global": {
      "languages": [
        {
          "language": "en",
          "default": true,
          "href": "https://developers.example.com/docs"
        },
        {
          "language": "de",
          "href": "https://developers.example.de/docs"
        },
        {
          "language": "fr",
          "href": "https://developers.example.fr/docs"
        },
        {
          "language": "es",
          "href": "https://developers.example.es/docs"
        }
      ]
    }
  }
}

​
Per-page locale links

Override the default language switcher URLs for specific pages using frontmatter. This allows you to link directly to the translated version of the current page instead of the homepage. Add locale-specific links to your page frontmatter using the pattern {language_code}_link:
api-reference/introduction.mdx
---
title: "API Introduction"
description: "Get started with our API"
de_link: "https://developers.example.de/docs/api-reference/introduction"
fr_link: "https://developers.example.fr/docs/api-reference/introduction"
es_link: "https://developers.example.es/docs/api-reference/introduction"
---
When a user switches languages on this page, they will be directed to the specific translated page URL instead of the default href configured in docs.json. This is particularly useful for:
  • Multi-domain documentation where each locale has its own domain
  • Documentation sites where not all pages are translated
  • Linking to equivalent pages across different documentation systems

​
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.

​
Automated translations

For automated translation solutions, contact the Mintlify sales team.

​
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 using relative paths in your translated content.
es/index.mdx
![Captura de pantalla del panel de control](/images/es/dashboard.png)

​
SEO for multi-language sites

Optimize each language version for search engines.

​
Page metadata

Include translated metadata in each file’s frontmatter:
fr/index.mdx
---
title: "Commencer"
description: "Apprenez à commencer avec notre produit."
keywords: ["démarrage", "tutoriel", "guide"]
---

​
hreflang tags

Mintlify automatically generates hreflang tags for each language version of your documentation to help search engines understand the relationships between translated pages.

​
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€
Include examples in the appropriate format for each language or use universally understood formats.

​
Maintain consistency

  • Maintain content parity across all languages to ensure every user gets the same quality of information.
  • Create a translation glossary for technical terms.
  • Keep the same content structure across languages.
  • Match the tone and style of your source content.
  • Use Git branches to manage translation work separately from main content updates.

​
Layout differences

Some languages require more or less space than English. Test your translated content on different screen sizes to ensure:
  • Navigation fits properly.
  • Code blocks don’t overflow.
  • Tables and other formatted text remain readable.
  • Images scale appropriately.

​
Character encoding

Ensure your development environment and deployment pipeline support UTF-8 encoding to properly display all characters in languages with different alphabets and special characters.