From b6ecbb8deaa27c8984a3d56fb1fb186490fba5a5 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 30 Apr 2026 23:22:11 +0000 Subject: [PATCH 1/8] docs: expand localization page with navigation overlay documentation Document the translation overlay feature for sidebar and tabs: - How to create fern/translations/{locale}/fern/docs.yml to translate product switcher names, navbar links, and top-level fields - How to create product-level overlays for section/page names - Version file translation support - Clear folder structure showing the overlay pattern - Summary table of overlay file locations - Complete example showing the full workflow Co-Authored-By: bot_apk --- .../docs/pages/localization/overview.mdx | 181 ++++++++++++++---- 1 file changed, 149 insertions(+), 32 deletions(-) diff --git a/fern/products/docs/pages/localization/overview.mdx b/fern/products/docs/pages/localization/overview.mdx index 03091849f1..531aa7ae75 100644 --- a/fern/products/docs/pages/localization/overview.mdx +++ b/fern/products/docs/pages/localization/overview.mdx @@ -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. +## Setup - +Make sure you're on the latest 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 +``` + + +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 +``` + +Use [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language codes (e.g., `en`, `ja`, `zh`, `fr`, `es`, `de`). + + + -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. - - - + + + + - - - - + + + + + + + + - - - - - + + + + + + @@ -62,50 +87,142 @@ Create a `translations` folder inside your `fern` directory, with a subfolder fo - + -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: 製品 ``` + + 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. + + - + -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ドキュメントへようこそ。 ``` - 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. + + +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`. + + + ```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`. - +## 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. From 28507adb3d029148edaea9934f0c65940036a90a Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 30 Apr 2026 23:25:26 +0000 Subject: [PATCH 2/8] fix: address vale style warnings Co-Authored-By: bot_apk --- fern/products/docs/pages/localization/overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/localization/overview.mdx b/fern/products/docs/pages/localization/overview.mdx index 531aa7ae75..03ef00367f 100644 --- a/fern/products/docs/pages/localization/overview.mdx +++ b/fern/products/docs/pages/localization/overview.mdx @@ -26,7 +26,7 @@ You maintain your default-language pages as usual. When you run `fern generate - ## Setup -Make sure you're on the latest Fern CLI: +First, upgrade the Fern CLI: ```bash fern upgrade @@ -46,7 +46,7 @@ translations: - lang: zh ``` -Use [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language codes (e.g., `en`, `ja`, `zh`, `fr`, `es`, `de`). +Use [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) two-letter language codes (e.g., `en`, `ja`, `zh`, `fr`, `es`, `de`). From 6d04bf4953e9130ce13a29fc48d8aee9cee54231 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 30 Apr 2026 23:29:39 +0000 Subject: [PATCH 3/8] docs: note BCP 47 locale tag support alongside ISO 639-1 codes Co-Authored-By: bot_apk --- fern/products/docs/pages/localization/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/localization/overview.mdx b/fern/products/docs/pages/localization/overview.mdx index 03ef00367f..ff27abe1ca 100644 --- a/fern/products/docs/pages/localization/overview.mdx +++ b/fern/products/docs/pages/localization/overview.mdx @@ -46,7 +46,7 @@ translations: - lang: zh ``` -Use [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) two-letter language codes (e.g., `en`, `ja`, `zh`, `fr`, `es`, `de`). +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/`. From 3307d56da739b03cea673d7cc58ed94bf2e31919 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 30 Apr 2026 23:30:51 +0000 Subject: [PATCH 4/8] docs: condense overlay reference section Co-Authored-By: bot_apk --- fern/products/docs/pages/localization/overview.mdx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/fern/products/docs/pages/localization/overview.mdx b/fern/products/docs/pages/localization/overview.mdx index ff27abe1ca..1d1f43ded4 100644 --- a/fern/products/docs/pages/localization/overview.mdx +++ b/fern/products/docs/pages/localization/overview.mdx @@ -175,18 +175,16 @@ Fern picks up the translations, renders the language switcher in the header, and -## How overlays work +## Overlay file reference -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 | +| Target | Overlay path | |---|---| -| Product switcher names, navbar links | `fern/translations/{locale}/fern/docs.yml` | +| Product switcher, 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. +Overlays merge into the base config — include only the fields you want to translate. Keep the same ordering and `slug` values as the base file. ## Example From 28891fd984f8100e5aadb6691f8c81640009bfd8 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 30 Apr 2026 23:31:45 +0000 Subject: [PATCH 5/8] docs: move granular overlay details and full example to llms-only tags Co-Authored-By: bot_apk --- .../docs/pages/localization/overview.mdx | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/fern/products/docs/pages/localization/overview.mdx b/fern/products/docs/pages/localization/overview.mdx index 1d1f43ded4..0dd5f74cd5 100644 --- a/fern/products/docs/pages/localization/overview.mdx +++ b/fern/products/docs/pages/localization/overview.mdx @@ -108,7 +108,10 @@ products: 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`: +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`. + + +Here's a full product-level overlay example. Entries are matched by position and `slug` — keep the same ordering and slug values as the base file. The `path` field can be omitted since it's inherited. ```yaml fern/translations/ja/fern/products/docs/docs.yml navigation: @@ -132,10 +135,7 @@ navigation: - page: バージョン - page: 製品 ``` - - - 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. - + @@ -175,6 +175,7 @@ Fern picks up the translations, renders the language switcher in the header, and + ## Overlay file reference | Target | Overlay path | @@ -186,11 +187,11 @@ Fern picks up the translations, renders the language switcher in the header, and Overlays merge into the base config — include only the fields you want to translate. Keep the same ordering and `slug` values as the base file. -## Example +## Complete example -Here's a minimal example translating an English docs site into Japanese: +A minimal setup translating an English docs site into Japanese: -```yaml fern/docs.yml {3-6} +```yaml fern/docs.yml instances: - url: your-org.docs.buildwithfern.com @@ -223,4 +224,5 @@ 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. +When a reader switches to Japanese, the sidebar shows translated section and page names, and translated page content is served where available. Any page without a translation file falls back to the English version. + From b9b83b5763af48e7494d3406d0ff1cc6db67ce28 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 30 Apr 2026 20:31:54 -0400 Subject: [PATCH 6/8] clarify and condense --- .../docs/pages/localization/overview.mdx | 112 +++--------------- 1 file changed, 15 insertions(+), 97 deletions(-) diff --git a/fern/products/docs/pages/localization/overview.mdx b/fern/products/docs/pages/localization/overview.mdx index 0dd5f74cd5..771870a4a7 100644 --- a/fern/products/docs/pages/localization/overview.mdx +++ b/fern/products/docs/pages/localization/overview.mdx @@ -24,17 +24,23 @@ 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. -## Setup +## 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. + + + + + +Localization requires the latest CLI version. ```bash fern upgrade ``` - + - + Add a `translations` key to your `docs.yml` listing each supported language. Mark one language as the default. @@ -46,13 +52,13 @@ translations: - 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/`. +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`). -Create a `translations` folder inside your `fern` directory, with a subfolder for each language code. This folder contains your translated content and navigation overrides. +Create a `translations` folder inside your `fern` directory. Each language declared in `docs.yml` needs a subfolder matching its locale code. This folder contains your translated content and navigation overrides. @@ -87,9 +93,9 @@ Create a `translations` folder inside your `fern` directory, with a subfolder fo - + -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. +To translate navigation items, create a matching file under `fern/translations/{locale}/` for any base config YAML you have — `docs.yml`, product files, [version files](/learn/docs/configuration/versions). Include only the fields you want to translate; everything else falls back to the default language. [Example PR](https://github.com/fern-api/docs/pull/5203/files) ```yaml fern/translations/ja/fern/docs.yml products: @@ -107,36 +113,6 @@ products: 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`. - - -Here's a full product-level overlay example. Entries are matched by position and `slug` — keep the same ordering and slug values as the base file. The `path` field can be omitted since it's inherited. - -```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: 製品 -``` - - @@ -157,12 +133,6 @@ Fernドキュメントへようこそ。 - - -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`. - - - ```bash @@ -173,56 +143,4 @@ Fern picks up the translations, renders the language switcher in the header, and - - - -## Overlay file reference - -| Target | Overlay path | -|---|---| -| Product switcher, 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/...` | - -Overlays merge into the base config — include only the fields you want to translate. Keep the same ordering and `slug` values as the base file. - -## Complete example - -A minimal setup translating an English docs site into Japanese: - -```yaml fern/docs.yml -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. Any page without a translation file falls back to the English version. - + \ No newline at end of file From 0326eb5a313e9d332ab2804b382e17b142de6cd1 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 30 Apr 2026 20:34:08 -0400 Subject: [PATCH 7/8] fix vale --- .vale/styles/FernStyles/Acronyms.yml | 1 + .vale/styles/FernStyles/Headings.yml | 1 + 2 files changed, 2 insertions(+) diff --git a/.vale/styles/FernStyles/Acronyms.yml b/.vale/styles/FernStyles/Acronyms.yml index 83d1694677..7af037cdcb 100644 --- a/.vale/styles/FernStyles/Acronyms.yml +++ b/.vale/styles/FernStyles/Acronyms.yml @@ -107,3 +107,4 @@ exceptions: - GEO - SPDX - BCP + - ISO diff --git a/.vale/styles/FernStyles/Headings.yml b/.vale/styles/FernStyles/Headings.yml index 97ef8e1b8f..856750e8d3 100644 --- a/.vale/styles/FernStyles/Headings.yml +++ b/.vale/styles/FernStyles/Headings.yml @@ -89,3 +89,4 @@ exceptions: - GEO - OG - BCP + - ISO From d5e785fed50e1ec1ef822ebf419b6fb14e98f847 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 30 Apr 2026 20:36:03 -0400 Subject: [PATCH 8/8] cross reference --- fern/products/docs/pages/localization/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/localization/overview.mdx b/fern/products/docs/pages/localization/overview.mdx index 771870a4a7..b7fdff6968 100644 --- a/fern/products/docs/pages/localization/overview.mdx +++ b/fern/products/docs/pages/localization/overview.mdx @@ -95,7 +95,7 @@ Create a `translations` folder inside your `fern` directory. Each language decla -To translate navigation items, create a matching file under `fern/translations/{locale}/` for any base config YAML you have — `docs.yml`, product files, [version files](/learn/docs/configuration/versions). Include only the fields you want to translate; everything else falls back to the default language. [Example PR](https://github.com/fern-api/docs/pull/5203/files) +To translate navigation items, create a matching file under `fern/translations/{locale}/` for any [base config YAML](/learn/docs/configuration/overview) you have — `docs.yml`, product files, version files, etc. Include only the fields you want to translate; everything else falls back to the default language. [Example PR](https://github.com/fern-api/docs/pull/5203/files) ```yaml fern/translations/ja/fern/docs.yml products: