Localization

Localization

Pre-release
Ship documentation in multiple languages from a single source
View as Markdown

Fern lets you publish your documentation in multiple languages from a single source. Readers switch languages from a dropdown in your site header, and each locale gets its own indexable URL for SEO.

You maintain your default-language pages as usual. When you run fern generate --docs, Fern auto-translates them into every configured language as part of the build, so your site rebuilds with up-to-date translations each time.

See it live on the i18n example site (source).

Localization is in alpha and under active development. Automated translation, search indexing, Ask Fern, and translated fern check errors are still in progress.

Reach out if you’re interested in implementing localization for your docs.

The manual setup below works today. Once localization is generally available, most of these steps will be handled for you.

1

Add a translations folder

Create a translations folder inside your fern directory, with a subfolder for each language using its ISO 639-1 code (e.g., fr, ja). Mirror your pages/ structure inside each language folder.

fern
fern.config.json
docs.yml
pages
introduction.mdx
getting-started.mdx
translations
fr
pages
introduction.mdx
getting-started.mdx
ja
pages
introduction.mdx
getting-started.mdx
2

Declare languages in docs.yml

Add a translations key listing each supported language. The first entry is the default.

docs.yml
1instances:
2  - url: your-org.docs.buildwithfern.com
3
4translations:
5  - lang: en
6  - lang: fr
7  - lang: ja
3

Add your translated content

Each translated .mdx mirrors its source page’s content. Use the sidebar-title frontmatter field to override the sidebar entry per language:

translations/fr/pages/introduction.mdx
1---
2sidebar-title: Introduction
3---
4
5Bienvenue dans la documentation.
4

Generate your docs

$fern generate --docs

When you regenerate your docs, Fern picks up the translations, renders the language switcher, and emits a sitemap entry per locale.