Skip to content

docs: expand localization page with navigation overlay documentation #5287

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
devalog merged 8 commits into from
May 1, 2026
Merged

docs: expand localization page with navigation overlay documentation #5287

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
b6ecbb8
docs: expand localization page with navigation overlay documentation
devin-ai-integration[bot] Apr 30, 2026
28507ad
fix: address vale style warnings
devin-ai-integration[bot] Apr 30, 2026
6d04bf4
docs: note BCP 47 locale tag support alongside ISO 639-1 codes
devin-ai-integration[bot] Apr 30, 2026
3307d56
docs: condense overlay reference section
devin-ai-integration[bot] Apr 30, 2026
28891fd
docs: move granular overlay details and full example to llms-only tags
devin-ai-integration[bot] Apr 30, 2026
b9b83b5
clarify and condense
devalog May 1, 2026
0326eb5
fix vale
devalog May 1, 2026
d5e785f
cross reference
devalog May 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 149 additions & 32 deletions fern/products/docs/pages/localization/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,36 +24,61 @@ You maintain your default-language pages as usual. When you run `fern generate -
[Reach out](mailto:support@buildwithfern.com) if you're interested in implementing localization for your docs.
</Note>

## Setup

<Accordion title="Early access setup">
First, upgrade the Fern CLI:

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

<Steps>

<Step title="Declare languages in docs.yml">

Add a `translations` key to your `docs.yml` listing each supported language. Mark one language as the default.

```yaml docs.yml
translations:
- lang: en
default: true
- lang: ja
- lang: zh
```

Fern supports both two-letter [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) codes (e.g., `en`, `ja`, `zh`) and full [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) locale tags (e.g., `ja-JP`, `pt-BR`, `zh-Hans-CN`). The locale code you choose here determines your translation folder name under `fern/translations/`.
Copy link
Copy Markdown
Contributor

@github-actions github-actions Bot Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'ISO' has no definition.


</Step>

<Step title="Add a translations folder">

Create a `translations` folder inside your `fern` directory, with a subfolder for each language using its [BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) (e.g., `fr-FR`, `ja-JP`). Mirror your `pages/` structure inside each language folder.
Create a `translations` folder inside your `fern` directory, with a subfolder for each language code. This folder contains your translated content and navigation overrides.

<Files>
<Folder name="fern" defaultOpen>
<File name="fern.config.json" />
<File name="docs.yml" />
<Folder name="pages" defaultOpen>
<File name="introduction.mdx" />
<File name="getting-started.mdx" />
<Folder name="products" defaultOpen>
<Folder name="docs">
<File name="docs.yml" />
</Folder>
</Folder>
<Folder name="translations" defaultOpen highlighted>
<Folder name="fr-FR" defaultOpen>
<Folder name="pages" defaultOpen>
<File name="introduction.mdx" />
<File name="getting-started.mdx" />
<Folder name="ja" defaultOpen>
<Folder name="fern" defaultOpen>
<File name="docs.yml" />
<Folder name="products">
<Folder name="docs">
<File name="docs.yml" />
</Folder>
</Folder>
</Folder>
</Folder>
<Folder name="ja-JP" defaultOpen>
<Folder name="pages" defaultOpen>
<File name="introduction.mdx" />
<File name="getting-started.mdx" />
<Folder name="products">
<Folder name="docs">
<Folder name="pages">
<File name="introduction.mdx" />
</Folder>
</Folder>
</Folder>
</Folder>
</Folder>
Expand All @@ -62,50 +87,142 @@ Create a `translations` folder inside your `fern` directory, with a subfolder fo

</Step>

<Step title="Declare languages in `docs.yml`">
<Step title="Translate your sidebar and tabs">

Add a `translations` key listing each supported language. The first entry is the default.
Create a navigation overlay file at `fern/translations/{locale}/fern/docs.yml` to translate the product switcher, navbar links, and other top-level fields. You only need to include the fields you want to override — everything else falls back to the default language.

```yaml docs.yml {4-7}
instances:
- url: your-org.docs.buildwithfern.com
```yaml fern/translations/ja/fern/docs.yml
products:
- display-name: ホーム
path: ./products/home/home.yml
subtitle: 開発者体験を向上させる製品

translations:
- lang: en-US
- lang: fr-FR
- lang: ja-JP
- slug: sdks
display-name: SDK
path: ./products/sdks/sdks.yml
subtitle: 複数の言語でクライアントライブラリを生成

- slug: docs
display-name: ドキュメント
path: ./products/docs/docs.yml
subtitle: 美しいインタラクティブなドキュメントサイトを生成
```

To translate section names and page names in the sidebar, create an overlay for each product file at `fern/translations/{locale}/fern/products/{product}/{product}.yml`:

```yaml fern/translations/ja/fern/products/docs/docs.yml
navigation:
- section: はじめに
contents:
- page: 概要
- page: 仕組み
- page: クイックスタート
- page: プロジェクト構成
- section: 設定
contents:
- page: 概要
- page: サイトレベルの設定
slug: site-level-settings
- section: ナビゲーション
contents:
- page: セクション、ページ、フォルダ
slug: navigation
- page: タブとタブバリアント
slug: tabs
- page: バージョン
- page: 製品
```

<Note>
Only include the fields you want to translate. The `slug` values must match the original — they're used to match entries, not translated. The `path` field can be omitted since it's inherited from the base file.
</Note>

</Step>

<Step title="Add your translated content">
<Step title="Translate page content">

Each translated `.mdx` mirrors its source page's content. Use the `sidebar-title` frontmatter field to override the sidebar entry per language:
Place translated `.mdx` files in `fern/translations/{locale}/products/` mirroring the original file structure. Use the `sidebar-title` frontmatter field to override the sidebar entry per language:

```mdx translations/fr-FR/pages/introduction.mdx
```mdx fern/translations/ja/products/docs/pages/getting-started/overview.mdx
---
sidebar-title: Introduction
sidebar-title: 概要
---

Bienvenue dans la documentation.
Fernドキュメントへようこそ。
```

<Tip>
You only need to translate the files you want to localize. Anything missing from a language folder — pages, images, or other assets — falls back to the default-language version.
You only need to translate the files you want to localize. Any page missing from a language folder falls back to the default-language version automatically.
</Tip>

</Step>

<Step title="Translate version files">

If your docs use [versions](/learn/docs/config/versions), you can translate version display names and navigation the same way — create an overlay at `fern/translations/{locale}/fern/versions/{version}.yml`.

</Step>

<Step title="Generate your docs">

```bash
fern generate --docs
```

When you regenerate your docs, Fern picks up the translations, renders the language switcher, and emits a sitemap entry per locale. You can also preview translations locally with `fern docs dev`.
Fern picks up the translations, renders the language switcher in the header, and emits a sitemap entry per locale. You can also preview translations locally with `fern docs dev`.

</Step>

</Steps>

</Accordion>
## How overlays work

Translation overlay files use a **merge strategy** — they don't replace the base configuration, they override specific fields within it.

| What you want to translate | Overlay file location |
|---|---|
| Product switcher names, navbar links | `fern/translations/{locale}/fern/docs.yml` |
| Sidebar sections, page names, tabs | `fern/translations/{locale}/fern/products/{product}/{product}.yml` |
| Version display names | `fern/translations/{locale}/fern/versions/{version}.yml` |
| Page content | `fern/translations/{locale}/products/{product}/pages/...` |

The overlay only needs to contain the fields you want to translate. For navigation overlays, entries are matched by their position in the list and by `slug` values — so keep the same ordering and slugs as the base file.

## Example

Here's a minimal example translating an English docs site into Japanese:

```yaml fern/docs.yml {3-6}
instances:
- url: your-org.docs.buildwithfern.com

translations:
- lang: en
default: true
- lang: ja
```

```yaml fern/translations/ja/fern/docs.yml
products:
- display-name: ドキュメント
path: ./products/docs/docs.yml
subtitle: ドキュメントサイトを生成
```

```yaml fern/translations/ja/fern/products/docs/docs.yml
navigation:
- section: はじめに
contents:
- page: 概要
- page: クイックスタート
```

```mdx fern/translations/ja/products/docs/pages/getting-started/overview.mdx
---
sidebar-title: 概要
---

ドキュメントへようこそ。このガイドでは...
```

When a reader switches to Japanese, the sidebar shows translated section and page names, and translated page content is served where available. For any page without a translation file, the English version is shown.
Loading