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.

​
Set default language

The first language in the languages array is automatically used as the default. To use a different language as the default, either reorder the array or add the default property:
docs.json
{
  "navigation": {
    "languages": [
      {
        "language": "es",
        "groups": [...]
      },
      {
        "language": "en",
        "groups": [...]
      }
    ]
  }
}
Alternatively, use the default property to override the order:
docs.json
{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [...]
      },
      {
        "language": "es",
        "default": true,
        "groups": [...]
      }
    ]
  }
}

​
Single language documentation

If you only want one language available without a language switcher, remove the languages field from your navigation configuration. Instead, define your navigation structure directly:
docs.json
{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["index", "quickstart"]
          }
        ]
      }
    ]
  }
}
This displays your documentation in a single language without the language switcher UI.
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
    ]
  }
}

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

​
External translation providers

If you work with your own translation vendors or regional translators, you can integrate their workflow with your Mintlify documentation using GitHub Actions or similar CI/CD tools.

​
Workflow overview

  1. Export source content - Extract MDX files that need translation.
  2. Send to translators - Provide files to your translation provider.
  3. Receive translations - Get translated MDX files back.
  4. Import and deploy - Add translated files to language directories and update navigation.

​
GitHub Actions example

This workflow automatically exports changed English content for translation when PRs merge to main:
.github/workflows/export-for-translation.yml
name: Export content for translation

on:
  push:
    branches: [main]
    paths:
      - '*.mdx'
      - '!es/**'
      - '!fr/**'
      - '!zh/**'

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Get changed files
        id: changed
        run: |
          echo "files=$(git diff --name-only HEAD~1 HEAD -- '*.mdx' ':!es/' ':!fr/' ':!zh/' | tr '\n' ' ')" >> $GITHUB_OUTPUT

      - name: Create translation package
        if: steps.changed.outputs.files != ''
        run: |
          mkdir -p translation-export
          for file in ${{ steps.changed.outputs.files }}; do
            cp "$file" translation-export/
          done

      - name: Upload translation package
        if: steps.changed.outputs.files != ''
        uses: actions/upload-artifact@v4
        with:
          name: translation-export-${{ github.sha }}
          path: translation-export/

​
Import translations workflow

This workflow validates and imports translated content when added via PR:
.github/workflows/import-translations.yml
name: Import translations

on:
  pull_request:
    paths:
      - 'es/**'
      - 'fr/**'
      - 'zh/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate frontmatter
        run: |
          for file in $(git diff --name-only origin/main...HEAD -- '*.mdx'); do
            if ! head -1 "$file" | grep -q '^---$'; then
              echo "Error: $file missing frontmatter"
              exit 1
            fi
          done

      - name: Check file structure
        run: |
          # Verify translated files match source structure
          for lang in es fr zh; do
            if [ -d "$lang" ]; then
              for file in $(find $lang -name '*.mdx'); do
                source_file="${file#*/}"
                if [ ! -f "$source_file" ]; then
                  echo "Warning: $file has no English source at $source_file"
                fi
              done
            fi
          done

​
Best practices for external translation workflows

  • Preserve frontmatter - Ensure translators keep YAML frontmatter intact, translating only title and description values.
  • Protect code blocks - Mark code blocks as “do not translate” for your vendors.
  • Use translation memory - Provide glossaries with technical terms that should remain in English or have specific translations.
  • Automate validation - Use CI checks to verify MDX syntax and frontmatter before merging translations.
  • Version control - Track the source version for each translation to identify outdated content.

​
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"]
---

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