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.

Translate the text with home.json

To share one homepage across languages, set homepage: { enabled: true, translations: true } in rdx.config.ts and default export your server component from components/home.tsx. If you already have a custom homepage, adapt that component in place. Replace homepage.component with translations: true so RDX loads your component from that path.

Wrap each translatable phrase in t() and use docsHref for documentation links.

components/home.tsx
import type { RdxTranslatedHomepageProps } from '@lexibase/rdx'
import { Home } from '@lexibase/rdx/ui/components/home'

export default function AtlasHome({ docsHref, t }: RdxTranslatedHomepageProps) {
  return (
    <Home
      title={t('Welcome to Atlas')}
      buttons={[{ label: t('Read the docs'), href: docsHref }]}
    />
  )
}

Run rdx i18n sync to create or update home.json beside the docs/ directory of each configured additional language:

pnpm rdx i18n sync

The command appends new literal phrases to each catalog with empty values. It preserves existing entries, including translations, metadata, and orphaned keys. Use rdx check to find orphaned keys and review them before removing them manually. Run rdx i18n sync again whenever the homepage adds phrases.

Fill in the values you want to translate. With the ptbr folder alias, the Portuguese file looks like this after translating the first phrase:

locale/ptbr/home.json
{
  "Welcome to Atlas": "Bem-vindo ao Atlas",
  "Read the docs": ""
}

Save catalogs as UTF-8. Files saved as UTF-8 with BOM are also supported when loading translations and running rdx i18n sync.

The empty Read the docs entry falls back to the original phrase, and docsHref still points to /pt-br/docs. rdx check and rdx build warn about missing translations and keys that no longer match a t('literal phrase') call in components/home.tsx. These warnings allow partial translations to ship.

Write phrases as literal t('…') calls in components/home.tsx so the check can find them. If you pass t to another component or helper, rename it, or call it with a dynamic value, the check warns with the file and line and skips orphan warnings because it cannot verify the entire catalog.

Keep t() in the server homepage and pass the translated strings to interactive child components. Edits to an existing catalog are picked up in development. Restart the dev server after adding or removing a catalog.

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.

Add $metadata to the same home.json that contains your translated phrases. The fields are optional and apply to the browser title, page description, and Open Graph and Twitter previews.

locale/ptbr/home.json
{
  "Welcome to Atlas": "Bem-vindo ao Atlas",
  "$metadata": {
    "title": "Atlas em português",
    "description": "Aprenda a criar e publicar documentação com Atlas."
  }
}

When metadata.metadataBase is set in rdx.config.ts, RDX generates canonical URLs and hreflang links for / and homepages with at least one translated t('literal phrase'). An empty catalog, outdated phrases, or $metadata alone leave the language out of the alternates. The language selector still lets readers open that homepage and reach the translated docs.

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.