Skip to content

Commit 54521dc

Browse files
fern-api[bot]devin-ai-integration[bot]bot_apkdevalog
authored
docs: expand localization page with navigation overlay documentation (#5287)
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Co-authored-by: bot_apk <apk@cognition.ai> Co-authored-by: Devin Logan <devinannlogan@gmail.com>
1 parent c996d53 commit 54521dc

3 files changed

Lines changed: 72 additions & 35 deletions

File tree

‎.vale/styles/FernStyles/Acronyms.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,3 +107,4 @@ exceptions:
107107
- GEO
108108
- SPDX
109109
- BCP
110+
- ISO

‎.vale/styles/FernStyles/Headings.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,3 +89,4 @@ exceptions:
8989
- GEO
9090
- OG
9191
- BCP
92+
- ISO

‎fern/products/docs/pages/localization/overview.mdx‎

Lines changed: 70 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -24,36 +24,67 @@ You maintain your default-language pages as usual. When you run `fern generate -
2424
[Reach out](mailto:support@buildwithfern.com) if you're interested in implementing localization for your docs.
2525
</Note>
2626

27-
28-
<Accordion title="Early access setup">
27+
## Early access setup
2928

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

3231
<Steps>
3332

33+
<Step title="Upgrade the Fern CLI">
34+
35+
Localization requires the latest CLI version.
36+
37+
```bash
38+
fern upgrade
39+
```
40+
41+
</Step>
42+
43+
<Step title="Declare languages in `docs.yml`">
44+
45+
Add a `translations` key to your `docs.yml` listing each supported language. Mark one language as the default.
46+
47+
```yaml docs.yml
48+
translations:
49+
- lang: en
50+
default: true
51+
- lang: ja
52+
- lang: zh
53+
```
54+
55+
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`).
56+
57+
</Step>
58+
3459
<Step title="Add a translations folder">
3560

36-
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.
61+
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.
3762

3863
<Files>
3964
<Folder name="fern" defaultOpen>
4065
<File name="fern.config.json" />
4166
<File name="docs.yml" />
42-
<Folder name="pages" defaultOpen>
43-
<File name="introduction.mdx" />
44-
<File name="getting-started.mdx" />
67+
<Folder name="products" defaultOpen>
68+
<Folder name="docs">
69+
<File name="docs.yml" />
70+
</Folder>
4571
</Folder>
4672
<Folder name="translations" defaultOpen highlighted>
47-
<Folder name="fr-FR" defaultOpen>
48-
<Folder name="pages" defaultOpen>
49-
<File name="introduction.mdx" />
50-
<File name="getting-started.mdx" />
73+
<Folder name="ja" defaultOpen>
74+
<Folder name="fern" defaultOpen>
75+
<File name="docs.yml" />
76+
<Folder name="products">
77+
<Folder name="docs">
78+
<File name="docs.yml" />
79+
</Folder>
80+
</Folder>
5181
</Folder>
52-
</Folder>
53-
<Folder name="ja-JP" defaultOpen>
54-
<Folder name="pages" defaultOpen>
55-
<File name="introduction.mdx" />
56-
<File name="getting-started.mdx" />
82+
<Folder name="products">
83+
<Folder name="docs">
84+
<Folder name="pages">
85+
<File name="introduction.mdx" />
86+
</Folder>
87+
</Folder>
5788
</Folder>
5889
</Folder>
5990
</Folder>
@@ -62,36 +93,42 @@ Create a `translations` folder inside your `fern` directory, with a subfolder fo
6293

6394
</Step>
6495

65-
<Step title="Declare languages in `docs.yml`">
96+
<Step title="Translate your navigation">
6697

67-
Add a `translations` key listing each supported language. The first entry is the default.
98+
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)
6899

69-
```yaml docs.yml {4-7}
70-
instances:
71-
- url: your-org.docs.buildwithfern.com
100+
```yaml fern/translations/ja/fern/docs.yml
101+
products:
102+
- display-name: ホーム
103+
path: ./products/home/home.yml
104+
subtitle: 開発者体験を向上させる製品
72105
73-
translations:
74-
- lang: en-US
75-
- lang: fr-FR
76-
- lang: ja-JP
77-
```
106+
- slug: sdks
107+
display-name: SDK
108+
path: ./products/sdks/sdks.yml
109+
subtitle: 複数の言語でクライアントライブラリを生成
78110
111+
- slug: docs
112+
display-name: ドキュメント
113+
path: ./products/docs/docs.yml
114+
subtitle: 美しいインタラクティブなドキュメントサイトを生成
115+
```
79116
</Step>
80117

81-
<Step title="Add your translated content">
118+
<Step title="Translate page content">
82119

83-
Each translated `.mdx` mirrors its source page's content. Use the `sidebar-title` frontmatter field to override the sidebar entry per language:
120+
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:
84121

85-
```mdx translations/fr-FR/pages/introduction.mdx
122+
```mdx fern/translations/ja/products/docs/pages/getting-started/overview.mdx
86123
---
87-
sidebar-title: Introduction
124+
sidebar-title: 概要
88125
---
89126
90-
Bienvenue dans la documentation.
127+
Fernドキュメントへようこそ。
91128
```
92129

93130
<Tip>
94-
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.
131+
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.
95132
</Tip>
96133

97134
</Step>
@@ -102,10 +139,8 @@ Bienvenue dans la documentation.
102139
fern generate --docs
103140
```
104141

105-
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`.
142+
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`.
106143

107144
</Step>
108145

109-
</Steps>
110-
111-
</Accordion>
146+
</Steps>

0 commit comments

Comments
 (0)