> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/docs/localization/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiIzZjk3YzVmOC1kMmQ4LTQwNGMtYjY4MS02MmEyNWQ1ZTllNTIiLCJleHAiOjE3NzczMjk0OTcsImlhdCI6MTc3NzMyOTE5N30.HRuZ2xNx6l7P5pMB235lSDfpyT51vporjORjHgog_1w
>
> 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 full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# Localization

Fern lets you publish your documentation in multiple languages from a single source. Readers switch languages from a dropdown in your site header and each locale gets its own indexable URL for SEO.

You maintain your default-language pages as usual. When you run `fern generate --docs`, Fern auto-translates them into every configured language as part of the build, so your site rebuilds with up-to-date translations each time.

<Frame caption="See it live on the [i18n example site](https://i18n.docs.buildwithfern.com/) ([source](https://github.com/fern-api/docs-examples/tree/main/i18n/fern)).">
  <video src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/3c6d56fd4ca19d24da617916d5786f3c49399d6e802b3d03dd04fed63658b614/products/docs/pages/localization/i18n.mp4" autoPlay loop playsInline muted />
</Frame>

<Note>
  Localization is in alpha and under active development. Automated translation, search indexing, Ask Fern, and translated `fern check` errors are still in progress.

  [Reach out](mailto:support@buildwithfern.com) if you're interested in implementing localization for your docs.
</Note>

<Accordion title="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="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.

      <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>

          <Folder name="translations" defaultOpen highlighted>
            <Folder name="fr" defaultOpen>
              <Folder name="pages" defaultOpen>
                <File name="introduction.mdx" />

                <File name="getting-started.mdx" />
              </Folder>
            </Folder>

            <Folder name="ja" defaultOpen>
              <Folder name="pages" defaultOpen>
                <File name="introduction.mdx" />

                <File name="getting-started.mdx" />
              </Folder>
            </Folder>
          </Folder>
        </Folder>
      </Files>
    </Step>

    <Step title="Declare languages in `docs.yml`">
      Add a `translations` key listing each supported language. The first entry is the default.

      ```yaml docs.yml {4-7}
      instances:
        - url: your-org.docs.buildwithfern.com

      translations:
        - lang: en
        - lang: fr
        - lang: ja
      ```
    </Step>

    <Step title="Add your translated content">
      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
      ---
      sidebar-title: Introduction
      ---

      Bienvenue dans la documentation.
      ```
    </Step>

    <Step title="Generate your docs">
      ```bash
      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`.
    </Step>
  </Steps>
</Accordion>