Skip to content
Features

Languages

Offer translated documentation with an optional content-language plugin.

The optional @lexibase/rdx-i18n plugin adds content languages and a language selector to the navbar. Authors supply the translations as Markdown files. It works on its own or with the optional versioning plugin.

Activate languages

From the documentation project root:

pnpm rdx add i18n

The command uses lang from rdx.config.ts as the primary language and asks for additional language tags, separated by commas, such as en, es-ES. It installs the plugin, adds its configuration and prepares the translation folders and runtime. Display labels use each language's native name when available; edit label to customize them. Empty folders include .gitkeep so they can be committed.

For scripts or a terminal without interactive input, provide the additional languages explicitly:

pnpm rdx add i18n --locales en,es-ES

Include at least one language different from your primary language. Repeating the command preserves existing plugin options, languages, translations and dependency versions.

Configure languages

Import the plugin in rdx.config.ts and add it to plugins. Keep the other settings in your configuration:

rdx.config.ts
import { defineConfig } from '@lexibase/rdx'
import { i18n } from '@lexibase/rdx-i18n'

export default defineConfig({
  metadata: { applicationName: 'My documentation' },
  lang: 'en',
  plugins: [
    i18n({
      locales: [
        { code: 'en', label: 'English' },
        { code: 'pt-BR', label: 'Português (Brasil)', folder: 'ptbr' },
        { code: 'es-ES', label: 'Español' },
      ],
    }),
  ],
})

lang identifies the primary language. Its entry belongs in the language list without a folder setting. Other entries can specify a folder alias; by default, the folder is the lower-case language tag. Labels are displayed as written.

To add another language later, add its entry to locales, create its locale/<folder>/docs/ directory and write the translated pages. Restart the development server. The plugin is installed once for all configured languages.

Organize translations

Keep primary content in docs/. Create locale/<folder>/docs/ for every secondary language. Mirror the structure of the original pages using the same folder and file names:

Folder
docs/
01-guides/
02-installation.mdx
locale/
ptbr/
docs/
01-guides/
02-installation.md
es-es/
docs/
01-guides/
02-installation.mdx

Translate the title, description, headings and body. Use navTitle to give the translated page a shorter sidebar label. Both .md and .mdx support RDX's Markdown components.

RDX matches translations by route. The numeric prefixes and file extension are omitted from the URL, so both files above map to guides/installation. Category labels come from the primary folder names by default. Category and page order follow the primary tree, including any order values in its frontmatter. Store shared images and downloads in root public/.

The examples above have English as the primary language. When English is a secondary language, its content belongs in locale/en/docs/ instead.

The selector preserves the page when changing languages. Language tags prefix the documentation URL:

  • /en/docs/guides/installation
  • /pt-br/docs/guides/installation
  • /es-es/docs/guides/installation

The ptbr folder alias still produces the pt-br language prefix. Existing unprefixed documentation links redirect to the primary language.

Restart the development server after enabling, disabling or changing configured languages so RDX can regenerate the route structure.

Search runs in the selected language and indexes the pages authored in it.

The menu lists the primary language and every configured additional language, including languages whose translations are still being written. A missing page uses the fallback described below.

Localize your homepage

When the homepage is enabled, / serves the primary language and a path such as /pt-br serves the homepage for that language. The language selector stays on the homepage when switching languages. The navbar logo opens the homepage in the language of the current documentation page.

Set homepage.enabled to true and configure your primary homepage as shown in the Homepage guide. To translate it, create home.tsx beside the translated docs/ directory and export the component as the default export. Use the same folder as the translated docs. For example, with the ptbr folder alias, create locale/ptbr/home.tsx for the /pt-br homepage.

Folder
components/
home.tsx
locale/
ptbr/
docs/
home.tsx
fr-fr/
docs/
locale/ptbr/home.tsx
import type { RdxHomepageProps } from '@lexibase/rdx'
import { Home } from '@lexibase/rdx/ui/components/home'

export default function PortugueseHome({ docsHref }: RdxHomepageProps) {
  return (
    <Home
      title="Bem-vindo ao Atlas"
      buttons={[{ label: 'Leia a documentação', href: docsHref }]}
    />
  )
}

Use docsHref for documentation links in both the primary and translated homepages. Share layouts and sections through components/ and write each translation in its own home.tsx.

When a language has only translated docs, RDX renders the primary homepage and keeps the selected language in the dropdown. In this example, /fr-fr shows the primary homepage and docsHref points to /fr-fr/docs.

Restart the development server after adding or removing a translated homepage.

Community translations

Set contributionUrl on the i18n plugin to invite readers to help translate:

rdx.config.ts
i18n({
  locales: [
    { code: 'en', label: 'English' },
    { code: 'pt-BR', label: 'Português', folder: 'ptbr' },
  ],
  contributionUrl: 'https://github.com/organization/project/tree/main/locale',
})

This adds Help translate below the language list and Translate this page in the missing-translation Callout. Both open the configured destination in a new tab. Their labels follow the interface language.

Use the full URL for your repository, contribution branch and documentation directory. For a monorepo, that might be https://github.com/organization/project/tree/main/apps/web/locale. You can also point to a translation contribution guide. Commit the translation directory to that branch before sharing its contribution link.

The locale/ directory contains the additional languages. The original pages remain in docs/; contributors use those paths to identify the corresponding translated files. For example, docs/guides/installation.mdx corresponds to locale/ptbr/docs/guides/installation.mdx in the configuration above. All documentation editions use the current contribution URL.

Missing translations

When a translation is absent, RDX displays the original page at the selected language URL, with a Callout explaining which language you are reading and a link to the original. It does not copy or translate files automatically.

Links inside that original content retain their original language so section anchors keep working. Sidebar and previous/next navigation stay in the selected language. A page absent from both trees returns 404.

Fallback copies are excluded from the sitemap and marked noindex, follow. With metadata.metadataBase configured, their canonical URL points to the original page. Actual translations have their own metadata and language alternates.

Validate content

rdx check checks the authored pages in every language, including links, sections and local assets. A translated page without a primary counterpart is reported as an error. Missing translations are allowed.

The lang setting also selects built-in interface messages. English and Brazilian Portuguese have interface catalogs; other content languages use English interface messages. Your translated documents and language labels remain as written.

With versioning

Configure both plugins in rdx.config.ts, in either order:

rdx.config.ts
import { defineConfig } from '@lexibase/rdx'
import { i18n } from '@lexibase/rdx-i18n'
import { versioning } from '@lexibase/rdx-versioning'

export default defineConfig({
  metadata: { applicationName: 'My documentation' },
  lang: 'en',
  plugins: [
    versioning(),
    i18n({
      locales: [
        { code: 'en', label: 'English' },
        { code: 'pt-BR', label: 'Português (Brasil)', folder: 'ptbr' },
      ],
    }),
  ],
})

Publish all configured languages with one command:

pnpm rdx version 1.0.0

The primary snapshot stays in versioned_docs/. Translated snapshots stay beside their live language trees:

Folder
versioned_docs/
version-1.0.0/
01-guides/
02-installation.mdx
locale/
ptbr/
docs/
01-guides/
02-installation.md
versioned_docs/
version-1.0.0/
01-guides/
02-installation.md
versions.json

RDX records the language inventory of each release in its snapshot metadata. Commit the complete snapshot directories, including their internal JSON files. Keep versions.json at the project root; one edition applies to every language. If copying a language fails, the new snapshots are removed and the version manifest stays unchanged.

Read a Portuguese snapshot at /pt-br/docs/1.0.0/guides/installation. Switching languages preserves the edition; switching editions preserves the language. Search stays within both selections. Missing translations display the primary page from that same edition, never a later translation from the live tree.

Snapshots created before language support contain primary-language content. Adding the plugin does not copy current translations into those snapshots. Changing a live translation's folder alias does not move existing snapshots. Keep the primary lang stable after publishing multilingual snapshots.

The versioning commands also archive, restore and advance the whole edition. Same-major redirects preserve the language and page. Retain the historical snapshot metadata so replaced-language URLs remain recognizable.