# Fumadocs UI (the default theme of Fumadocs): 翻譯
URL: /zh-TW/docs/ui/translations
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/translations.zh-TW.mdx

為 UI 加入翻譯

## 概覽 [#overview]

所有官方 Fumadocs 套件預設皆使用英文，您也可以為其他語言新增翻譯。

> 本頁主要說明新增 UI 翻譯的細節；若需要完整說明，請參閱[國際化](/docs/next/internationalization)指南。

### 單一 (Singular)  [#singular]

**單一** (Singular) 是指只為單一語言新增翻譯：

```ts title="lib/layout.shared.tsx"
import { defineTranslations } from 'fumadocs-core/i18n';
import { uiTranslations } from 'fumadocs-ui/i18n';

export const translations = defineTranslations().extend(uiTranslations()).add({
  // [標籤]：[翻譯文字]
  'Search(search trigger)': '搜尋文檔',
});
```

> 請務必在所有 `.extend()` 呼叫完成**之後**，才呼叫 `.add()`。

請將翻譯內容傳入 `<RootProvider />`。

```tsx
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
      // [!code ++]
      i18n={i18nProvider(translations)}
    >
      {children}
    </RootProvider>
  );
}
```

### 多語言 [#multilingual]

為多種語言定義翻譯。此功能需要標準的 [i18n](/docs/next/internationalization) 設定。

```ts title="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({
    // [語系代碼]：[翻譯]
    cn: {
      // [標籤]：[翻譯]
      'Search(search trigger)': '搜尋文檔',
    },
  });
```

將翻譯內容傳給 `<RootProvider />`。

```tsx
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
      // [!code ++]
      i18n={i18nProvider(translations, locale)}
    >
      {children}
    </RootProvider>
  );
}
```

## 語言包 [#language-packs]

語言包為 `fumadocs-ui` 及 Fumadocs OpenAPI 等多項整合提供翻譯。

```npm
npm i @fumadocs/language
```

> 若官方語言包中沒有您需要的語言，歡迎到[我們的儲存庫](https://github.com/fuma-nama/fumadocs)貢獻翻譯。

使用 `preset()` 套用語言包：

```ts tab="Singular"
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())
  // 依照您已設定的整合加入對應的擴充功能，例如 Fumadocs OpenAPI：
  .extend(openapiTranslations())
  // 繁體中文
  .preset(zhTW());
```

```ts tab="Multilingual"
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';
import { i18n } from '@/lib/i18n';

export const translations = i18n
  .translations()
  .extend(uiTranslations())
  // 依照您設定的整合加入對應的擴充功能，例如 Fumadocs OpenAPI：
  .extend(openapiTranslations())
  // 將繁體中文翻譯套用至語系代碼 "cn"
  .preset('cn', zhTW());
```

### 自訂語言包 [#custom-packs]

您也可以建立並發布自己的語言包。

例如，`zh-TW` 語言包的結構如下：

```ts twoslash
import type { TranslationPreset } from 'fumadocs-core/i18n';
import * as OpenAPI from 'fumadocs-openapi/i18n';
import * as UI from 'fumadocs-ui/i18n';
import * as Story from '@fumadocs/story/i18n';

const translations = {
  displayName: '繁體中文',
  'Server URL(playground server select)': '伺服器 URL',
  'Variant(story controls)': '變體',
  // ...
} satisfies Partial<UI.Translations & OpenAPI.Translations & Story.Translations>;

export function zhTW(): TranslationPreset<keyof typeof translations> {
  return {
    name: 'zh-TW',
    value: translations,
  };
}
```

## 擴充功能 [#extensions]

擴充功能會宣告可供翻譯的標籤，只有已註冊的標籤才會傳送至用戶端酬載。

### 自訂擴充功能 [#custom-extension]

如果您正在為 Fumadocs 開發社群套件，可以建立擴充功能來註冊您自己的翻譯。

首先，請安裝 Fumadocs 所使用的翻譯工具組：

```npm
npm i @fuma-translate/react
```

```ts tab="i18n.ts" twoslash
import type { TranslationExtension } from 'fumadocs-core/i18n';

const keys = [
  // 鍵的格式："your label(additional context)"
  'Hello {user}(welcome screen)',
] as const;

export function myTranslations(): TranslationExtension<(typeof keys)[number]> {
  return { keys };
}
```

```tsx tab="Reference"
'use client';
import { useTranslations } from '@fuma-translate/react';

export function Comp() {
  const t = useTranslations();

  return (
    <div>
      {t('Hello {user}', {
        note: 'welcome screen',
        variables: {
          user: '...',
        },
      })}
    </div>
  );
}
```

> 為求簡潔，此處省略相關說明；您可以參閱 [Fuma Translate](https://fuma-translate.vercel.app) 的文件，了解如何編譯翻譯鍵值 &amp; 型別，而非直接寫死在程式碼中。

使用者可以這樣使用您的擴充功能：

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

export const translations = defineTranslations()
  // [!code ++]
  .extend(myTranslations())
  .add({
    'Hello {user}(welcome screen)': '你好 {user}',
  });
```