Skip to content

Nextra 集成 ​

在基于 Next.js App Router 的 Nextra 4 文档站点中使用 init -t ui-nextra 和 docsOutput.style: "nextra"。该预设是 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)

当你在一次 sync 运行中同时翻译页面内容、_meta.ts 侧边栏标签和主题字典模块时,请启用 features.translateDocs。

页面布局 ​

支持 i18n 的 Nextra 4 会将源语言区域的 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,并使 ai-i18n-tools.config.json 中的 targetLocales 与这些语言环境代码以及 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 会自动收集 docsRoot 下的 _meta.ts、_meta.tsx 和 _meta.js,翻译 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 文件。

示例项目 ​

examples/nextra-docs — 英文源文件位于 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/`.

可选:用于 app/ React 的 t()(混合) ​

默认值: _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 单例是不安全的:并发请求会共享它。该示例改用无状态查找。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 引导程序时,它才重要,因为该引导程序会按 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,而不会触及文档管道。

示例 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-Hans/guide/getting-started)
[Guide](/zh-Hans/guide/getting-started.mdx)[Guide](/zh-Hans/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)。ai-i18n-tools.config.json 中的 sourceLocale 可以是 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 许可证发布。