I’ll introduce how to build a documentation site that supports both English (default) and Japanese using Mintlify’s standard features.

The goal is to implement sophisticated language switching functionality like Cursor’s documentation (docs.cursor.com).

Steps for Multilingual Support

Multilingual support in Mintlify involves only two main steps:

1. Add language definitions to docs.json
2. Create language-specific directories and place translated documents

Official documentation: Languages - Navigation - Mintlify

1. docs.json Configuration

First, edit the configuration file docs.json in your project root. Add a languages property at the top level of the file and define an array of languages you want to support.

Since we’re supporting English (en) and Japanese (ja), we’ll write it as follows. The first language in the array is treated as the default language.

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["en/overview", "en/quickstart", "en/development"]
          }
        ]
      },
      {
        "language": "ja",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["ja/overview", "ja/quickstart", "ja/development"]
          }
        ]
      }
    ]
  }
}

Just by adding this configuration, a language switcher selector will automatically appear in the site header.

2. Directory Structure Changes and Translation File Placement

Next, place the documentation files as configured in the docs.json above.

Implementation Example (Pull Request)

I’ll share the Pull Requests from when I actually implemented multilingual support using this procedure. You can check the specific file differences, which should deepen your understanding.

• feat: implement multilingual support with English and Japanese by shige · Pull Request #2
• feat: implement multilingual documentation with Japanese translation support by shige · Pull Request #96

Summary

With Mintlify, you can build a full-featured multilingual documentation site through very simple steps: adding a few lines to docs.json and creating language-specific directories.

Since the framework nicely abstracts the internationalization (i18n) mechanisms, developers can focus on content translation. If your project targets users worldwide, I encourage you to try using this feature to make your documentation multilingual.

That’s all from the Gemba.