Skip to content

Nextra 整合 ​

使用 init -t ui-nextra 和 docsOutput.style: "nextra" 為基於 Next.js App Router 的 Nextra 4 文件網站提供支援。此預設集是 doc-system 的別名,具有空的 localeSubpath 並保留 BCP-47 地區資料夾名稱(localePathLowercase 預設為 false,因此資料夾保持為 pt-BR、zh-Hans 等)。

另請參閱文件,以及可執行的 examples/nextra-docs 示範。

快速開始 ​

bash
ai-i18n-tools init -t ui-nextra -P gemini
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync   # or: ai-i18n-tools sync
pnpm run build       # Next.js build (project-specific script)

翻譯頁面內容、_meta.ts 側邊欄標籤及主題詞典模組時,在單一 sync 執行作業中啟用 features.translateDocs。

頁面版面 ​

Nextra 4 的 i18n 功能會將來源語系的 MDX 檔案存放在語系資料夾下(當來源語系為英文時,通常是 content/en/)。sourceLocale 可以是任何語言。翻譯副本會寫入同層級的語系資料夾中:

text
content/en/index.mdx              →  content/pt-BR/index.mdx
content/en/guide/getting-started.mdx  →  content/zh-Hans/guide/getting-started.mdx

設定一個 docs[] 區塊:

json
{
  "contentPaths": ["content/en"],
  "outputDir": "content",
  "docsOutput": {
    "style": "nextra",
    "docsRoot": "content/en",
    "rewriteNextraLinks": true
  }
}

將 contentPaths 指向以 sourceLocale 編寫的 .mdx 檔案和目錄。該語言可以是任何語言。將 docsRoot 設定為 content/ 內的來源語系資料夾 (例如,當來源為英文時,設為 content/en)。

連接 Nextra 國際化:在 next.config 中設定 i18n.locales 和 defaultLocale,並讓 targetLocales 在 ai-i18n-tools.config.json 中與這些地區代碼和 content/{locale}/ 資料夾名稱保持一致。

在現有網站中啟用 i18n ​

僅限英文的 Nextra 4 網站需要一個語系資料夾、一個路由參數,以及 Next.js i18n 設定,才能讓 translate-docs 有地方可寫入。首次設定會使用 新增 i18n 到網站或文件網站 上的提示。字典提示 是針對相同路由和字典的詳細後續步驟。檢查清單:

  • 將 MDX 移至 content/en/ (英文是一個語系資料夾,而非內容根目錄)。
  • 在 next.config 中設定 i18n.locales 和 defaultLocale。
  • 一個 app/[lang]/ 路由、getPageMap('/${lang}') 和 <Layout i18n={…}>。
  • app/_dictionaries/en.ts 加上 get-dictionary.ts,並傳入 <Layout>、<Navbar> 和 <Footer>。
  • 可選的 proxy.ts,它會重新匯出 nextra/locales (請參閱 可選的語系代理)。
  • targetLocales 與那些語系代碼對齊,然後是 sync。

主題字串 ​

Nextra 主題字串 (editLink、搜尋佔位符、頁腳等) 不會從 Markdown 中提取。請在 TypeScript 字典模組中編寫英文詞串 (例如 app/_dictionaries/en.ts),並在 translate-docs 內部翻譯它:

json
{
  "features": {
    "translateDocs": true
  },
  "docs": [
    {
      "contentPaths": ["content/en"],
      "outputDir": "content",
      "nextraDictionaryPath": "app/_dictionaries/en.ts",
      "docsOutput": {
        "style": "nextra",
        "docsRoot": "content/en"
      }
    }
  ]
}

工具會寫入 app/_dictionaries/{locale}.ts(預設範本:{dir}/{locale}.ts)。在 app/_dictionaries/get-dictionary.ts 中載入每個地區的模組,並將翻譯後的字串傳遞給 <Layout>、<Search>、<Footer> 及相關主題元件。

請勿 將 json[] 用於 Nextra 主題字典字串——該模式僅適用於不相關的應用程式地區套件。

側邊欄標籤 (_meta.ts) ​

Nextra 3+ 使用 TypeScript _meta.ts / _meta.tsx 檔案作為側邊欄結構和標題。當 docsOutput.style 為 "nextra" 時,translate-docs 會自動將 _meta.ts、_meta.tsx 和 _meta.js 收集到 docsRoot 下,翻譯 export default { … } 中繼對應中的字串常值,並在 content/{locale}/** 下寫入鏡像檔案。

建議的模式: 將英文常值保留在 content/en/**/_meta.ts 內(與 swr-site 相同):

text
content/en/_meta.ts           English sidebar labels (source)
content/pt-BR/_meta.ts        Translated copy (generated by translate-docs)

選用:使用 docs[].nextraMetaGlob 覆寫收集,或使用 docs[].nextraMetaTranslatableKeys 限制可翻譯的屬性名稱(預設:title、display、breadcrumb)。

請勿 手動編寫 JSON 側邊檔案(i18n/meta.en.json)或匯入翻譯 JSON 的精簡 _meta.ts 檔案——當英文變更時,使用 sync / translate-docs 重新產生地區 _meta 檔案。

範例專案 ​

範例/Nextra 文件 — 英文來源位於 content/en/,已提交的 pt-BR 和 zh-Hans 頁面樹,內聯 _meta.ts 檔案,以及 app/_dictionaries/{locale}.ts。一個伺服器元件 (app/_components/feedback-links.tsx) 透過平面套件查找使用 t(),以便自訂外殼字串可以與字典並存。在連接埠 3070 上執行 pnpm run dev。

代理程式提示:字典與路由 ​

當網站仍有寫死的版面配置字串且沒有 content/en/ 樹狀結構時,請使用此提示。它會遵循預設路徑 (字典 + _meta.ts + translate-docs),且不會引入 t()。

字典與路由提示
markdown
# Add Nextra 4 i18n with a theme dictionary

## Context

ai-i18n-tools translates Nextra page bodies, `_meta.ts` object literals, and the
theme dictionary module (`nextraDictionaryPath`, usually
`app/_dictionaries/en.ts`) with `translate-docs`. The English sentence in that
dictionary is the source text. Do not translate strings yourself. Reference:
https://github.com/wsj-br/ai-i18n-tools/tree/main/examples/nextra-docs

## Scope

Edit `next.config`, `app/[lang]/layout.tsx`, `app/_dictionaries/en.ts`,
`app/_dictionaries/get-dictionary.ts`, and move MDX under `content/en/`. Skip
`docsRepositoryBase` (a URL). Keep native language names in a `LOCALE_LABELS`
map untranslated (`English`, `Português (Brasil)`). Do not move `_meta.ts`
sidebar labels into the dictionary or into `t()`.

## Call shape

- `next.config`: `i18n.locales` and `defaultLocale`.
- English MDX and `_meta.ts` live under `content/en/`. `getPageMap('/${lang}')`
  loads the matching tree.
- `app/_dictionaries/en.ts` exports the English shell strings (`siteTitle`, `footer`,
  `editLink`, search placeholder, table-of-contents title, last-updated label).
  `get-dictionary.ts` dynamically imports `./${locale}`.
- Pass those fields into `<Layout>`, `<Navbar>`, and `<Footer>`. Set
  `<Layout i18n>` from `LOCALE_LABELS`.
- Config: `features.translateDocs`, `docsOutput.style: "nextra"`,
  `docsRoot: "content/en"`, `nextraDictionaryPath: "app/_dictionaries/en.ts"`.
  `targetLocales` matches `i18n.locales` except the default locale.

## Order

1. Route, config, and dictionary wiring.
2. Move existing MDX into `content/en/` and point `contentPaths` at that folder.
3. Ask the user to run `sync`. Do not write `app/_dictionaries/pt-BR.ts` or
   `content/pt-BR/` by hand.

## Do not

- Do not translate, rename, or reword the English dictionary strings.
- Do not add `t()`, `getRequestConfig`, or a `dictionary.ts` filename. The
  English module is `app/_dictionaries/en.ts`.
- Do not duplicate a string in both the dictionary and a later `t()` call.
- Do not hand-edit generated locale dictionaries or locale `_meta.ts` files.

## Verify

- `pnpm build` passes.
- `/` shows the English dictionary strings. After `sync`, one non-English route
  shows translated shell strings and page titles.
- Sidebar labels come from `content/en/**/_meta.ts`, not from the dictionary.

## Report back

List files changed, each layout string you left untranslated and why (URLs,
native language names), and any MDX you were not sure belonged under
`content/en/`.

選用:t() 適用於 app/ React(混合) ​

預設: _meta.ts 物件字面值和 app/_dictionaries/en.ts 由 translate-docs 翻譯。這些外殼字串不需要 t()。

選用混合模式: 自訂伺服器元件可以呼叫 t("source sentence") 和 translate-ui。句子是以 sourceLocale 撰寫,它可以是任何語言。請勿將字典字串或 _meta.ts 標題複製到那些呼叫中。extract 只會看到 t() 內的常值,因此 ui.sourceRoots 應只列出包含那些呼叫的資料夾(範例使用 app/_components),而非 app/_dictionaries。

在伺服器元件中,帶有 changeLanguage 的模組層級 i18next 單例 (singleton) 是不安全的:因為並行請求會共用它。範例改用無狀態 (stateless) 查詢。getT(lang) 會為目標語系載入 locales/{lang}.json,將來源路由視為一個空的套件 (因為英文字面值本身就是文本),並使用來自 ai-i18n-tools/runtime 的 interpolateTemplate 進行內插。預留位置是 {{name}},使用 ASCII 字詞作為鍵。這與 examples/astro-website/src/i18n/t.ts 的概念相同。

該查詢不會選取複數形式。需要 plurals: true 的元件應該在客戶端元件中使用來自 連接 i18next 的 i18next 路徑,或使用每個請求各自的 createInstance()。

混合模式的設定,位於現有文件區塊旁:

  • features.translateUIStrings
  • ui.sourceRoots — 包含 t() 呼叫的資料夾
  • ui.stringsJson
  • ui.flatOutputDir

範例的 sourceLocale 是 en-GB,而網站路由是 en。使用無狀態查詢時,en 路由不需要套件,所以這種不匹配並不重要。只有當您將此元件切換到 i18next 啟動程序 (bootstrap) 時,這才重要,因為它會以 sourceLocale 作為套件的鍵。

內容預設管線選用替代方案
MDX 頁面主體translate-docs—
_meta.ts / _meta.tsx 物件標題translate-docs重構為 JSX 中的 t()(混合模式)
app/ 版面、_components/nextraDictionaryPath + 字典 .tst() + translate-ui

請參閱 examples/nextra-docs 中的 app/_components/feedback-links.tsx 和 lib/ui-t.ts。在該範例中,pnpm run i18n:sync-ui 會執行擷取和 translate-ui,而不會動到文件管線 (pipeline)。

AI 代理程式提示範例 (在字典旁新增 t() 時,複製到 Cursor 或其他程式碼助理):

混合模式 t() 提示
markdown
# Add a stateless t() lookup to a Nextra 4 server component

## Context

MDX pages, `_meta.ts`, and `app/_dictionaries/en.ts` stay on `translate-docs`.
Do not duplicate those strings in `t()`. This task adds `t("source sentence")`
only in custom components that the dictionary does not cover. The literal is the
catalog key and is written in `sourceLocale`, which can be any language. Do not translate any string.

Follow `lib/ui-t.ts` and `app/_components/feedback-links.tsx` in
https://github.com/wsj-br/ai-i18n-tools/tree/main/examples/nextra-docs

## Scope

Edit the named components and `ai-i18n-tools.config.json`. Do not edit
`app/_dictionaries`, `content/**/_meta.ts`, or generated locale trees. Skip
URLs, native language names, and `docsRepositoryBase`.

## Call shape

Create `lib/ui-t.ts`. `getT(lang)` loads `locales/{lang}.json` through a
dynamic-import map for target locales, uses an empty bundle for the source
route, and returns
`(source, vars) => interpolateTemplate(flat[source] ?? source, vars ?? {})` with
`interpolateTemplate` imported from `ai-i18n-tools/runtime`.

Replace hardcoded sentences in the named server components with `t("source sentence")`. The sentence is written in `sourceLocale`, which can be any language.
A placeholder is `t("You are reading {{page}}.", { page })`.

Do not use `getRequestConfig` (that is a next-intl API) and do not call
`changeLanguage` on a shared i18next instance. This lookup does not resolve
plurals. Leave plural copy on the i18next client path.

Set `features.translateUIStrings`, `ui.sourceRoots` to only the folders that
contain `t()` calls, `ui.stringsJson`, and `ui.flatOutputDir`.

## Order

1. Add `lib/ui-t.ts` and the `t()` calls.
2. Set the four `ui` config keys.
3. Run `ai-i18n-tools extract` (or `sync-ui`). Do not hand-write
   `locales/*.json`.

## Do not

- Do not translate, rename, or reword the source sentences.
- Do not put `t()` keys in `app/_dictionaries` or move `_meta.ts` titles into
  `t()`.
- Do not hand-edit `strings.json` or flat locale files.
- Do not change layout or Nextra theme props that already receive dictionary
  strings.

## Verify

- `extract` writes a non-empty catalog containing the new sentences and nothing
  from the dictionary.
- The project build passes.
- The source route still shows the English sentences. After `translate-ui`, one
  non-English route renders the translated component.

## Report back

List files changed, each string you left in the dictionary on purpose, and any
plural or server-concurrency case you did not convert.

連結慣例 ​

Nextra 透過 Next.js i18n(/guide/getting-started、/pt-BR/guide/getting-started)提供地區前置詞路由。頁面內連結應保持地區中立(/guide/getting-started),讓 Next.js 自動附加目前的地區前置詞。

啟用內建的標準化工具,讓 translate-docs 自動修正每個翻譯檔案中的連結:

json
"docsOutput": {
  "style": "nextra",
  "docsRoot": "content/en",
  "rewriteNextraLinks": true
}

當 style 為 "nextra" 時,rewriteNextraLinks 預設為啟用。

在來源語系中撰寫經過標準化工具後
[Guide](content/en/guide/getting-started.mdx)[Guide](/zh-Hant/guide/getting-started)
[Guide](/zh-Hant/guide/getting-started.mdx)[Guide](/zh-Hant/guide/getting-started)
[Demo](https://github.com/org/repo)不變(完整 URL)

撰寫規則

  • 跨頁文件連結:在英文 MDX 中使用 語系中立的網站路由 (/guide/…),或 content/en/… / 相對 .mdx 路徑,並讓標準化工具在 sync 期間重寫它們。
  • 內容樹外部的儲存庫檔案:使用 完整 URL。
  • 請勿手動編輯 content/<locale>/ 中的連結 — 請使用 sync / translate-docs 重新產生。

選用地區代理程式 ​

Nextra 為 i18n 網站提供地區偵測代理程式。從專案根目錄的 proxy.ts 匯出:

ts
export { proxy } from 'nextra/locales'

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|icon.svg|apple-icon.png|manifest|_pagefind).*)',
  ],
}

網站語系代碼與 sourceLocale: Nextra 和 Next.js 在 next.config、content/{locale}/ 和 NEXT_LOCALE cookie 中使用簡短的路由代碼 (en、pt-BR、zh-Hans)。sourceLocale 在 ai-i18n-tools.config.json 中可以是 BCP-47 標籤,例如 en-GB,用於翻譯品質 — 該標籤不是網站路由。如果瀏覽器 cookie 或 Accept-Language 解析為 i18n.locales 之外的標籤 (例如,當僅設定 en 時為 en-GB),Nextra 的預設代理可能會陷入無限重新導向。examples/nextra-docs 示範會包裝 nextra/locales,以便在委派之前將無效的 cookie 和路徑重設為預設網站語系。

這不適用於 output: 'export' 靜態匯出。請參閱 Nextra i18n 文件。

另請參閱 設定 — docsOutput 和 輸出版面配置。

採用 MIT 授權條款釋出。