diff --git a/.vale/styles/FernStyles/Acronyms.yml b/.vale/styles/FernStyles/Acronyms.yml index 83d169467..7af037cdc 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 97ef8e1b8..856750e8d 100644 --- a/.vale/styles/FernStyles/Headings.yml +++ b/.vale/styles/FernStyles/Headings.yml @@ -89,3 +89,4 @@ exceptions: - GEO - OG - BCP + - ISO diff --git a/fern/products/docs/pages/localization/overview.mdx b/fern/products/docs/pages/localization/overview.mdx index 03091849f..b7fdff696 100644 --- a/fern/products/docs/pages/localization/overview.mdx +++ b/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. - - +## Early access setup 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. + +```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`). + + + -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. - - - + + + + - - - - + + + + + + + + - - - - - + + + + + + @@ -62,36 +93,42 @@ 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. +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: 美しいインタラクティブなドキュメントサイトを生成 +``` - + -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. @@ -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`. - - - + \ No newline at end of file