Skip to Content

Internationalization

Publish your site in multiple languages.

List your languages, and Fumapress adds the URLs and links between translations. A page without a translation shows the page of the fallback language.

Setup

List the Languages

Define them and pass them to createPress():

press.config.tsx
import { createPress } from "fumapress";
import { defineDocs } from "fumadocs-mdx/macro";
import { defineI18n } from "fumadocs-core/i18n";

const docs = defineDocs({ dir: "content" });

const i18n = defineI18n({
  languages: ["en", "zh"],
  defaultLanguage: "en",
});

export const app = createPress({ docs: docs.toFumadocsSource() }, { i18n });

export default app.config({
  ui: {
    translations: i18n.translations(),
  },
});

Translate the Pages

Add the language to the file name. This works for pages and meta.json:

meta.json
meta.zh.json
get-started.mdx
get-started.zh.mdx

A language without a file inherits the page from the fallback language. If only the English file exists, /zh/get-started still exists and shows the English page.

Inherited pages get noindex and are left out of the sitemap, RSS feed, llms-full.txt and Open Graph images, since search engines shouldn't see them as translations.

Translate the UI

The search dialog, table of contents and other UI have their own strings. The language pack translates them for Chinese:

npm i @fumapress/language
press.config.tsx
import { zhTW } from "@fumapress/language/zh-tw";

export default app.config({
  ui: {
    translations: i18n.translations().preset("zh", zhTW()), 
  },
});

The language pack has zhCN and zhTW. For other languages, or to change single strings, use .add():

press.config.tsx
i18n
  .translations()
  .preset("zh", zhTW())
  .add({
    en: { displayName: "English" },
    zh: {
      displayName: "Chinese",
      "Search(search dialog)": "搜尋文檔",
      "Blog(blog)": "博客",
    },
  });

See the Fumadocs Translations API for details.

Language Prefixes

Each language has a URL prefix. To drop the prefix of the default language, set hideLocale:

const i18n = defineI18n({
  languages: ["en", "zh"],
  defaultLanguage: "en",
  hideLocale: "default-locale", 
});
Source"never" (default)"default-locale"
content/index.mdx/en, /zh/, /zh
content/setup.mdx/en/setup, /zh/setup/setup, /zh/setup
Blog index (plugin page)/en/blog, /zh/blog/blog, /zh/blog

With "never", / redirects to /en. When /en has no page, like with content under a baseDir, the root and the navbar title link to the first page of en.

hideLocale: "always" isn't supported, because Fumapress uses the prefix to tell languages apart.

localizePath() adds the prefix, unless hideLocale hides it. Use it in ui.layoutProps, in plugins, and with getPressContext() on custom pages.

press.config.tsx
this.localizePath("zh", "/setup"); // "/zh/setup"

hreflang Tags

Pages link their translations for search engines, with tags like this one:

<link rel="alternate" hreflang="zh-Hans" href="https://acme.dev/cn/setup" />

hreflang must be a BCP 47 tag. When a language code isn't one, map it:

press.config.tsx
export default app.config({
  site: { hreflang: { cn: "zh-Hans", tw: "zh-Hant" } },
});

Custom Pages

Each page in src/pages is created once per language, under its prefix, with a lang prop:

src/pages/about.tsx
import type { WakuRouteProps } from "fumapress";
import type { app } from "../../press.config";

export default function Page({ lang }: WakuRouteProps<typeof app>) {
  return <h1>{lang === "zh" ? "关于" : "About"}</h1>;
}

To keep a single copy of a page, in the default language, set autoI18n: false in getConfig().

Last updated on

On this page