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 <provider>]
# 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/）。翻译后的副本会写入同级的语言环境文件夹：

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 指向你的英文 .mdx 文件和目录。将 docsRoot 设置为 content/ 内的英文语言环境文件夹。

配置 Nextra 国际化：在 next.config 中设置 i18n.locales 和 defaultLocale，并使 ai-i18n-tools.config.json 中的 targetLocales 与这些语言环境代码以及 content/{locale}/ 文件夹名称保持一致。

主题字符串

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 { … } meta 映射中的字符串字面量，并在 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。在端口 3070 上运行 pnpm run dev。

可选：用于 app/ React 的 t()（混合）

默认： _meta.ts / _meta.tsx 对象字面量字符串在 translate-docs 内部翻译 — 无需 t()。

可选混合模式： 团队还可以使用 t() + translate-ui 来处理仅存在于 JSX 组件主体中的 app/ 布局外壳、自定义 MDX 组件或 _meta.tsx 标签（超出 v1 中的对象字面量提取范围）。除非你明确将侧边栏标签重构为组件，否则这不会替代 meta 文件的 translate-meta。

内容	默认流水线	可选替代方案
MDX 页面主体	translate-docs	—
_meta.ts / _meta.tsx 对象标题	translate-docs	重构为 JSX 中的 t()（混合模式）
app/ 布局，_components/	nextraDictionaryPath + 字典 .ts	t() + translate-ui

AI 代理提示词示例（在将布局外壳迁移到 t() 时，复制到 Cursor 或其他编码代理中）：

Add i18n to our Nextra 4 app/ layout using ai-i18n-tools translate-ui (optional hybrid).

Context:
- We already translate MDX pages and _meta.ts via translate-docs (default).
- We want t() in app/[lang]/layout.tsx and app/_components/ for labels not covered by nextraDictionaryPath.
- English-as-key: t("Edit this page on GitHub") in source; strings.json + locales/{locale}.json from extract + translate-ui.
- Do not move _meta.ts sidebar labels into t() unless we explicitly ask — translate-docs handles _meta object literals.

Requirements:
1. Wire getRequestConfig / i18n provider for the app router locale param.
2. Replace hard-coded layout strings with t() calls; keep structure and Nextra theme APIs unchanged.
3. Enable features.translateUIStrings, set ui.sourceRoots to app/ (and mdx-components if needed).
4. Do not duplicate dictionary.ts strings that nextraDictionaryPath already translates — pick one approach per string.

After editing: run extract, translate-ui (or sync), verify en + one target locale in dev.

链接约定

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和输出布局。