mintlify__docs/guides/internationalization.mdx

---
title: "Internationalization"
description: "Set up multi-language documentation to reach global audiences."
keywords: ["internationalization", "i18n", "multi-language", "translations", "localization", "language switcher"]
---

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](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). Place translated files in these directories with the same structure as your default language.

<Expandable title="supported language codes">
- `ar` - Arabic
- `cs` - Czech
- `zh` or `zh-Hans` - Chinese (Simplified)
- `zh-Hant` - Chinese (Traditional)
- `de` - German
- `en` - English
- `es` - Spanish
- `fr` - French
- `he` - Hebrew
- `hi` - Hindi
- `id` - Indonesian
- `it` - Italian
- `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
- `ua` - Ukrainian
- `uz` - Uzbek
- `vi` - Vietnamese
</Expandable>

```text 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
```

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

## Configure the language switcher

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

```json 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:

```json docs.json
{
  "navigation": {
    "languages": [
      {
        "language": "es",
        "groups": [...]
      },
      {
        "language": "en",
        "groups": [...]
      }
    ]
  }
}
```

Alternatively, use the `default` property to override the order:

```json 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:

```json 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.

<Tip>
  Translate navigation labels like group or tab names to match the language of the content. This creates a fully localized experience for your users.
</Tip>

### Global navigation

To add global navigation elements that appear across all languages, configure the `global` object in your `docs.json` navigation.

```json 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](mailto:gtm@mintlify.com).

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

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.

This GitHub Actions workflow automatically exports changed English content for translation when PRs merge to main.

```yaml .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: |
          for file in ${{ steps.changed.outputs.files }}; do
            mkdir -p "translation-export/$(dirname "$file")"
            cp "$file" "translation-export/$file"
          done

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

This GitHub Actions workflow validates and imports translated content when added via PR.

```yaml .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.

```mdx 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:

```mdx 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.