Languages

Languages add a selector that lets readers switch between translated versions of your documentation.

Use language navigation when you maintain real translated pages, not just machine-translated fragments. A language switcher is most useful when the same core onboarding, settings, and API reference pages exist in more than one language.

​

When to use languages

Use languages when:

• you have translated docs for a meaningful part of the user journey
• each language should have its own sidebar labels
• translated pages live at stable paths such as /fr/quickstart
• users should be able to keep their language preference as they move across tabs and dropdowns

If you only have one translated article, link to it from the page instead of adding a full language selector.

​

How languages work

Language navigation lives under navigation.languages.

Each language entry has:

• language: the language code, such as en, fr, es, or de
• default: whether this language should be selected by default
• groups: the sidebar groups and pages for that language

The default language can use regular paths like quickstart. Non-default languages usually use a language prefix like fr/quickstart.

​

Basic example

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "default": true,
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["quickstart", "settings/navigation"]
          }
        ]
      },
      {
        "language": "fr",
        "groups": [
          {
            "group": "Commencer",
            "pages": ["fr/quickstart", "fr/settings/navigation"]
          }
        ]
      }
    ]
  }
}

This creates a language selector with English and French. The French version points to pages under /fr/*.

​

Add translated pages

Create translated MDX files in the matching folder structure.

docs/
  quickstart.mdx
  settings/
    navigation.mdx
  fr/
    quickstart.mdx
    settings/
      navigation.mdx
  layout.json

Only add a translated page to the language navigation after the file exists. If a path is missing, users may land on a fallback page or a missing route.

​

Use languages with tabs

Language navigation works with top-level tabs. Put tabbed page paths inside each language’s groups.

{
  "topAnchor": {
    "name": "Home",
    "icon": "house"
  },
  "tabs": [
    {
      "name": "API Reference",
      "url": "api-reference",
      "icon": "square-terminal"
    }
  ],
  "navigation": {
    "languages": [
      {
        "language": "en",
        "default": true,
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["quickstart"]
          },
          {
            "group": "API Reference",
            "pages": ["api-reference/index", "api-reference/authentication"]
          }
        ]
      },
      {
        "language": "fr",
        "groups": [
          {
            "group": "Commencer",
            "pages": ["fr/quickstart"]
          },
          {
            "group": "Reference API",
            "pages": ["fr/api-reference/index", "fr/api-reference/authentication"]
          }
        ]
      }
    ]
  }
}

​

Use languages with API reference pages

For generated API pages, keep the route and OpenAPI operation references consistent.

If the English API page uses:

---
openapi: docsalot-cli-v1 GET /documentations
---

The French page can point to a translated spec:

---
openapi: docsalot-cli-v1-fr GET /documentations
---

This lets the French API reference render translated operation names and descriptions while keeping canonical API paths.

​

Agent-first setup

If you use the DocsAlot CLI with Claude, Codex, or another coding agent, ask it to create the translated structure and preview it.

use docsalot cli to add a French language option, translate the getting started and settings pages, update layout.json, and run a preview locally

For API documentation:

use docsalot cli to create a French API reference from the existing OpenAPI pages, add it to the language selector, and run a preview locally

Publish after review:

use docsalot cli to push this documentation to remote and publish

​

Common mistakes

• Do not add a language selector before there is enough translated content to make it useful.
• Do not list translated pages that do not exist.
• Do not mix translated sidebar labels with untranslated page paths unless that fallback is intentional.
• Keep API paths canonical even when operation titles and descriptions are translated.