Translations

Overview

All official Fumadocs packages use English by default, you can add translations for other languages.

This page mainly covers details for adding UI translations, you may be interested in the full Internationalization guide instead.

Singular

Singular refers to adding translations for only one language:

lib/layout.shared.tsx

import { defineTranslations } from 'fumadocs-core/i18n';
import { uiTranslations } from 'fumadocs-ui/i18n';

export const translations = defineTranslations().extend(uiTranslations()).add({
  // [label]: [translation]
  'Search(search trigger)': '搜尋文檔',
});

.add() should only be called after all .extend() calls.

Pass the translations to <RootProvider />.

import { RootProvider } from 'fumadocs-ui/provider/<framework>';
import { i18nProvider } from 'fumadocs-ui/i18n';
import { translations } from '@/lib/layout.shared';

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <RootProvider
      i18n={i18nProvider(translations)}
    >
      {children}
    </RootProvider>
  );
}

Multilingual

Define translations for multiple languages, this requires a standard i18n setup.

lib/layout.shared.tsx

import { defineTranslations } from 'fumadocs-core/i18n';
import { uiTranslations } from 'fumadocs-ui/i18n';
import { i18n } from '@/lib/i18n';

export const translations = i18n
  .translations()
  .extend(uiTranslations())
  .add({
    // [locale code]: [translations]
    cn: {
      // [label]: [translation]
      'Search(search trigger)': '搜尋文檔',
    },
  });

Pass the translations to <RootProvider />.

import { RootProvider } from 'fumadocs-ui/provider/<framework>';
import { i18nProvider } from 'fumadocs-ui/i18n';
import { translations } from '@/lib/layout.shared';

export function Layout({ locale, children }: { locale: string; children: React.ReactNode }) {
  return (
    <RootProvider
      i18n={i18nProvider(translations, locale)}
    >
      {children}
    </RootProvider>
  );
}

Language Packs

Language packs provide translations for fumadocs-ui and several other integrations like Fumadocs OpenAPI.

npm i @fumadocs/language

If your desired language is missing in the official language packs, we welcome contributions to our repository.

Use preset() to consume language packs:

import { defineTranslations } from 'fumadocs-core/i18n';
import { openapiTranslations } from 'fumadocs-openapi/i18n';
import { uiTranslations } from 'fumadocs-ui/i18n';
import { zhTW } from '@fumadocs/language/zh-tw';

export const translations = defineTranslations()
  .extend(uiTranslations())
  // add extensions according to the integrations you configured, e.g. Fumadocs OpenAPI:
  .extend(openapiTranslations())
  // Traditional Chinese
  .preset(zhTW());

Custom Packs

You can also create & publish your own language packs.

For example, the structure of zh-TW language pack looks like:

import type {  } from 'fumadocs-core/i18n';
import * as  from 'fumadocs-openapi/i18n';
import * as  from 'fumadocs-ui/i18n';
import * as  from '@fumadocs/story/i18n';

const  = {
  : '繁體中文',
  'loading...(playground server select)': '載入中...',
  'No Variant(story controls)': '沒有變體',
  // ...
} satisfies <. & . & .>;

export function (): <keyof typeof > {
  return {
    : 'zh-TW',
    : ,
  };
}

Extensions

Extensions declare the available labels for translations, only registered labels will be sent to client payload.

Custom Extension

If you are building community packages for Fumadocs, you can create extensions to register your own translations.

To begin, install the translations toolkit Fumadocs use:

npm i @fuma-translate/react

import type {  } from 'fumadocs-core/i18n';

const  = [
  // key format: "your label(additional context)"
  'Hello {user}(welcome screen)',
] as ;

export function (): <(typeof )[number]> {
  return {  };
}

While skipped for simplicity, you can see the docs of Fuma Translate to learn how to compile translation keys & types, rather than hardcoding it.

Consumers can use your extension like:

import { defineTranslations } from 'fumadocs-core/i18n';
import { myTranslations } from 'my-package/i18n';

export const translations = defineTranslations()
  .extend(myTranslations())
  .add({
    'Hello {user}(welcome screen)': '你好 {user}',
  });