Skip to content

Update localization docs: BCP-47 codes and fallback behavior #5202

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 3 commits into from
Apr 28, 2026
Merged

Update localization docs: BCP-47 codes and fallback behavior #5202

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
92cbc77
Update localization docs: BCP-47 codes and fallback behavior
devin-ai-integration[bot] Apr 28, 2026
51d64af
restructure
devalog Apr 28, 2026
1f4e3af
fix vale
devalog Apr 28, 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
1 change: 1 addition & 0 deletions .vale/styles/FernStyles/Acronyms.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,3 +106,4 @@ exceptions:
- WSS
- GEO
- SPDX
- BCP
1 change: 1 addition & 0 deletions .vale/styles/FernStyles/Headings.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,3 +88,4 @@ exceptions:
- WSS
- GEO
- OG
- BCP
18 changes: 11 additions & 7 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 @@ -33,7 +33,7 @@ The manual setup below works today. Once localization is generally available, mo

<Step title="Add a translations folder">

Create a `translations` folder inside your `fern` directory, with a subfolder for each language using its [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g., `fr`, `ja`). Mirror your `pages/` structure inside each language 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.

<Files>
<Folder name="fern" defaultOpen>
Expand All @@ -44,13 +44,13 @@ Create a `translations` folder inside your `fern` directory, with a subfolder fo
<File name="getting-started.mdx" />
</Folder>
<Folder name="translations" defaultOpen highlighted>
<Folder name="fr" defaultOpen>
<Folder name="fr-FR" defaultOpen>
<Folder name="pages" defaultOpen>
<File name="introduction.mdx" />
<File name="getting-started.mdx" />
</Folder>
</Folder>
<Folder name="ja" defaultOpen>
<Folder name="ja-JP" defaultOpen>
<Folder name="pages" defaultOpen>
<File name="introduction.mdx" />
<File name="getting-started.mdx" />
Expand All @@ -71,9 +71,9 @@ instances:
- url: your-org.docs.buildwithfern.com

translations:
- lang: en
- lang: fr
- lang: ja
- lang: en-US
- lang: fr-FR
- lang: ja-JP
```

</Step>
Expand All @@ -82,14 +82,18 @@ translations:

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

```mdx translations/fr/pages/introduction.mdx
```mdx translations/fr-FR/pages/introduction.mdx
---
sidebar-title: Introduction
---

Bienvenue dans la documentation.
```

<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.
</Tip>

</Step>

<Step title="Generate your docs">
Expand Down
Loading