> This page is for Docs.

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For task-scoped instructions for coding agents working in a Fern project, see https://buildwithfern.com/learn/home/fern-instructions.md.

# Localization

> **Enterprise feature**
>
> This feature is available only for the [Enterprise plan](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com).

Fern lets you publish your documentation in multiple languages from a single set of source files. Readers switch languages from a dropdown in the header, [search](/learn/docs/customization/search) is scoped to the active language, and each locale has its own URL so search engines can index it separately.

You supply the translations and Fern handles the rest: rendering a language switcher in the header, scoping each locale to its own URL path, and falling back to the default language for any page you haven't translated yet.

> **Note**
>
> Localization is under active development. Ask Fern, `fern check` errors, and API Reference pages are still in progress.
>
> [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.

#### Upgrade the Fern CLI

Localization requires the latest CLI version.

```bash
fern upgrade
```

#### Declare languages in \`docs.yml\`

Add a `translations` key to your `docs.yml` listing each supported language. Mark one language as the default.

**`docs.yml`**

```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`).

#### Add a translations 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.

#### Translate your navigation

For each [base config YAML](/learn/docs/configuration/overview) you have — `docs.yml`, product files, version files — create a matching file under `fern/translations/{locale}/` at the same relative path and mirror its structure.

Within an entry, include only the fields you want to translate (`display-name`, `subtitle`, `section`, `page`, `link`, `api`); anything you omit falls back to the base file. Add a `slug:` to pin the base URL when the page name is an English term like `markdown` or `api-catalog`. A slug matches on its last segment, so `customization/voice` also works. Entries without a slug match their base counterparts in order. [Example PR](https://github.com/fern-api/docs/pull/5203/files)

#### Product switcher

**`fern/translations/ja/fern/docs.yml`**

```yaml fern/translations/ja/fern/docs.yml
products:
  - display-name: ホーム
    path: ./products/home/home.yml
    subtitle: 開発者体験を向上させる製品

  - slug: sdks
    display-name: SDK
    path: ./products/sdks/sdks.yml
    subtitle: 複数の言語でクライアントライブラリを生成

  - slug: docs
    display-name: ドキュメント
    path: ./products/docs/docs.yml
    subtitle: 美しいインタラクティブなドキュメントサイトを生成
```

#### Sidebar navigation

**`fern/translations/ja/fern/products/docs/docs.yml`**

```yaml fern/translations/ja/fern/products/docs/docs.yml
navigation:
  - section: はじめに
    contents:
      - page: 概要
      - page: クイックスタート
        slug: quickstart
  - section: AI 機能
    contents:
      - page: 概要
      - page: Markdown アクセス
        slug: markdown
      - page: API カタログ検出
        slug: api-catalog
      - section: llms-txt
        contents:
          - page: 概要
            slug: llms-txt
          - page: Agent 指示
```

#### Tabs and API Reference

Tab names, including changelog tabs, go under `tabs` keyed by tab ID. Inside an `api` layout, a package entry uses the package key with `title` and `contents`, and an endpoint entry uses `endpoint: "METHOD /path"` with `title`. Endpoint entries match by `slug`, or by HTTP method when that method appears only once among sibling endpoints; otherwise they match in order. `section` entries in an `api` layout translate the corresponding API sections.

**`fern/translations/ja/fern/products/docs/docs.yml`**

```yaml fern/translations/ja/fern/products/docs/docs.yml
tabs:
  changelog:
    display-name: 変更履歴
navigation:
  - tab: api-reference
    layout:
      - api: API リファレンス
        layout:
          - agents:
              title: エージェント
              contents:
                - endpoint: POST /agents
                  title: エージェントを作成
      - link: ステータスページ
```

These entries translate sidebar labels only. API Reference pages serve default-language content unless the locale has its own translated API definition.

> **Warning**
>
> Field-level fallback only applies within an entry. If a page is in the base nav but missing from the localized YAML, the localized URL serves the default-language page — even when a translated `.mdx` exists. Register every page you [translate](#translate-page-content) here too.

#### Translate page content

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:

**`fern/translations/ja/products/docs/pages/getting-started/overview.mdx`**

```mdx fern/translations/ja/products/docs/pages/getting-started/overview.mdx
---
sidebar-title: 概要
---

Fernドキュメントへようこそ。
```

> **Tip**
>
> You only need to translate the files you want to localize. Any page that's registered in the localized navigation but has no matching `.mdx` falls back to the default-language file automatically.
>
> Adding a translated `.mdx` alone isn't enough to localize a page — the page must also have an entry in the [localized navigation YAML](#translate-your-navigation). Without a localized nav entry, the page falls back to the default language even when a translation file exists.

#### Generate your docs

```bash
fern generate --docs
```

Fern picks up the translations, renders the language switcher in the header, and emits a sitemap and [`llms.txt`](/learn/docs/ai-features/llms-txt#localized-sites) per locale. Pages that fall back to default-language content, including API Reference pages for an API without a translated definition, stay accessible at the localized URL but are marked [`noindex`](/learn/docs/seo/setting-seo-metadata#indexing) and excluded from that locale's sitemap and `llms.txt`. You can also preview translations locally with `fern docs dev`.