docs: expand localization page with navigation overlay documentation

.vale/styles/FernStyles/Acronyms.yml

@@ -107,3 +107,4 @@ exceptions:
   - GEO
   - SPDX
   - BCP
+  - ISO

.vale/styles/FernStyles/Headings.yml

@@ -89,3 +89,4 @@ exceptions:
   - GEO
   - OG
   - BCP
+  - ISO

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

@@ -24,36 +24,67 @@ 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>
 
-
-<Accordion title="Early access setup">
+## Early access setup
 
 The manual setup below works today. Once localization is generally available, most of these steps will be handled for you.
 
 <Steps>
 
+<Step title="Upgrade the Fern CLI">
+
+Localization requires the latest CLI version.
+
+```bash
+fern upgrade
+```
+
+</Step>
+
+<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`).
+
+</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. Each language declared in `docs.yml` needs a subfolder matching its locale 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>
@@ -62,36 +93,42 @@ Create a `translations` folder inside your `fern` directory, with a subfolder fo
 
 </Step>
 
-<Step title="Declare languages in `docs.yml`">
+<Step title="Translate your navigation">
 
-Add a `translations` key listing each supported language. The first entry is the default.
+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 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: 美しいインタラクティブなドキュメントサイトを生成
+```
 </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>
@@ -102,10 +139,8 @@ Bienvenue dans la documentation.
 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>
+</Steps>