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 示例。
快速开始
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 可以是任何语言。翻译副本会被写入同级的语言区域文件夹中:
content/en/index.mdx → content/pt-BR/index.mdx
content/en/guide/getting-started.mdx → content/zh-Hans/guide/getting-started.mdx配置一个 docs[] 块:
{
"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 中进行翻译:
{
"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 相同):
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()。
字典和路由提示
# 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.translateUIStringsui.sourceRoots— 包含t()调用的文件夹ui.stringsJsonui.flatOutputDir
示例的 sourceLocale 是 en-GB,站点路由是 en。使用无状态查找时,en 路由不需要包,因此这种不匹配无关紧要。只有当您将此组件切换到 i18next 引导程序时,它才重要,因为该引导程序会按 sourceLocale 为包建立索引。
| 内容 | 默认流水线 | 可选替代方案 |
|---|---|---|
| MDX 页面主体 | translate-docs | — |
_meta.ts / _meta.tsx 对象标题 | translate-docs | 重构为 JSX 中的 t()(混合模式) |
app/ 布局,_components/ | nextraDictionaryPath + 字典 .ts | t() + 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() 提示
# 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 自动修复每个翻译文件中的链接:
"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 中导出它:
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和输出布局。