l10n

Configure localization (internationalization) for your project to support multiple languages. This includes setting up the language picker, organizing translated content, and defining language-specific labels.

The localization feature enables you to serve your project in multiple languages. You can fully localize both the content of project pages and the labels of UI components.

You can include translations for the following types of content:

• Markdown, OpenAPI, and GraphQL documents - Content in Markdown, YAML, JSON, or SDL documents
• Navbar, footer, and sidebar labels - Labels for items in navigation menus
• Base UI components - Labels for bundled components (e.g., Login button, search placeholder)
• Content on React pages - Headers, tiles, and other content in React components

To store translated files, your project must have a @l10n folder at the root, with a subfolder for each additional supported language. Files outside the @l10n folder should be in the default language.

your-project/├──@l10n/│   ├──es-ES/│   │   ├──index.md│   │   └──translations.yaml│   ├──fr-FR/│   │   ├──index.md│   │   └──translations.yaml│   └──ja/│       ├──index.md│       └──translations.yaml├──index.md├──translations.yaml└──redocly.yaml

To switch between languages, target language files in the localization folders must have the same structure as source language files in the root directory. You can think of each language subfolder as the "root directory" of each localization.

Language subfolder names can contain only letters, numbers, and - or _ symbols. Redocly recommends using IETF language tags like en or en-US.

Common language tags consist of:

• Language code: Two-letter lowercase codes from ISO 639-1: en, es, fr, ja
• Script subtag: Four-letter script code from ISO-15924: Hans, Hant
• Region subtag: Two-letter uppercase country codes from ISO 3166-1: US, ES, FR, JP

Use as few tags as necessary to differentiate between localization languages.

A translations.yaml file in each language subfolder and the root directory stores translation keys for base UI components, navigation, and React pages. When a language doesn't have a translation key defined, the project uses the key from the default language, or falls back to default values.

A page with no translation for the selected locale displays in the default language, without an explanation.

To explain why a page displays in a language other than the selected one, set showMissingTranslationNotice to true on the locale. The notice uses the language of the selected locale:

l10n:
  defaultLocale: en
  locales:
    - code: en
      name: English
    - code: fr
      name: French
      showMissingTranslationNotice: true

The notice appears on Markdown pages and on API documentation pages, below the breadcrumbs. The reader can close the notice for the page.

The text comes from the missingTranslationNotice translation keys, which Redocly provides for every language with bundled translations. To change the text, define the keys in the translations.yaml file of the locale. The content key supports Markdown, for example a link to your contribution guide:

missingTranslationNotice.title: Cette page n'est pas encore traduite
missingTranslationNotice.content: Vous consultez la version en {{language}}. [Aidez-nous à traduire](/contribute).

The {{language}} placeholder displays the name of the default locale, as defined in the locales option.

A page that uses a custom template doesn't display the notice, because the template controls its own layout. To display the notice in a custom template, add the MissingTranslationNotice component. The component renders only on pages that need the notice:

import { MissingTranslationNotice } from '@redocly/theme/components/MissingTranslationNotice/MissingTranslationNotice';

export default function MyTemplate({ children }) {
  return (
    <div>
      <MissingTranslationNotice />
      {children}
    </div>
  );
}

The following example shows a complete localization configuration for a project supporting multiple languages:

First, set up your folder structure:

your-project/├──@l10n/│   ├──es-ES/│   │   ├──index.md│   │   ├──api-docs/│   │   │   └──museum-api.yaml│   │   └──translations.yaml│   ├──fr-FR/│   │   ├──index.md│   │   ├──api-docs/│   │   │   └──museum-api.yaml│   │   └──translations.yaml│   └──ja/│       ├──index.md│       ├──api-docs/│       │   └──museum-api.yaml│       └──translations.yaml├──index.md├──api-docs/│   └──museum-api.yaml├──translations.yaml└──redocly.yaml

Then configure your locales in redocly.yaml:

l10n:
  defaultLocale: en
  locales:
    - code: en
      name: English
    - code: es-ES
      name: Spanish (Spain)
    - code: fr-FR
      name: French (France)
    - code: ja
      name: Japanese

navbar:
  items:
    - label: Home
      labelTranslationKey: nav.home
      page: /
    - label: API Documentation
      labelTranslationKey: nav.api.docs
      page: /api-docs/

footer:
  items:
    - label: Support
      labelTranslationKey: footer.support
      href: /support

For a minimal setup with just language switching:

l10n:
  defaultLocale: en
  locales:
    - code: en
      name: English
    - code: es
      name: Spanish
    - code: fr
      name: French

Redocly provides default translations for the following languages:

• en - English (United States)
• ar - Arabic
• hi - Hindi
• de - German
• es - Spanish
• fr - French
• it - Italian
• ja - Japanese
• ko - Korean
• pl - Polish
• pt - Portuguese (Portugal)
• pt-BR - Portuguese (Brazil)
• ru - Russian
• uk - Ukrainian
• zh - Chinese (Simplified)

• Localize UI labels - Configure translation keys for navigation and UI components to support multiple languages
• Predefined translation keys - Complete list of predefined translation keys for base UI components and interface elements
• Localize content - Translate your Markdown and API documentation files for comprehensive international support