Skip to content
Last updated

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.

How localization works

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.

Supported content types

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

Folder structure

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 naming

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.

Translation files

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.

Options

OptionTypeDescription
defaultLocalestringREQUIRED Name of the default locale (the language of the files outside of the @l10n folder).
localesLocale objectList of all locales, including the default locale

Locale object

OptionTypeDescription
codestringLanguage code. Must match the name of the language subfolder inside the @l10n folder or the defaultLocale code. The format of the code is lang-COUNTRY or lang, where lang is the language code and COUNTRY is the country code. For example, en-US for English (United States) and fr-FR for French (France), or en for English. More specific fallback locales are supported, for example de-AT falls back to de;
namestringLanguage name that is displayed in the language picker.

Examples

Complete localization setup

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:

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

Basic localization configuration

For a minimal setup with just language switching:

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

Supported default translations

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)

Resources

  • Localize UI labels - Configure translation keys for navigation and UI components to support multiple languages
  • Translation keys reference - 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
 
Next page