---
url: /docs/agentbuff-stack/languages.md
---
# 全站语言与翻译

当前模板默认启用英文与简体中文，保留可选西班牙语。官网、产品公开页、工作台、相关邮件、核心使用指南和教程界面支持双语；历史迭代及验收记录保留中文。产品仍在本地迭代，不接真实产品；静态官网与双语教程已单独授权发布。

## 配置产品语言

唯一入口为 `packages/core/website.ts` 的 `i18n`。英文必须排第一项，`metadata.language` 保持 `en`。中文的标语、两行首页标题、描述和全部方案说明放在 `translations.zh`，不能为空。可选西语读取 `translations.es`。

```ts
i18n: {
  locales: ["en", "zh"],
  translations: {
    zh: { /* 完整中文产品文案，参考源码 */ },
    es: null,
  },
},
```

以上是结构示意，不是完整可运行配置。仅英文产品可使用 `locales: ["en"]`，停用语言的译文可设为 `null`。运行 `bun run config:check` 后重建全部应用。重复或未知语言、启用但缺少产品说明会拒绝检查及构建。

不添加浏览器语言自动跳转、语言 Cookie 或新环境密钥。语言由网址明确表达；修改启用列表需要完整替换构建资产，避免旧页面残留。

## 页面范围与位置

| 页面 | 英文 | 中文 |
| --- | --- | --- |
| 首页、功能、价格 | `/`、`/features`、`/pricing` | `/zh/`、`/zh/features`、`/zh/pricing` |
| 工具、博客、联系与页脚页面 | 原路径 | `/zh` 加原路径 |
| 登录、注册、找回与重置 | 原路径 | `/zh` 加原路径 |
| 工作台、任务、文件、历史、积分、购买 | 原路径 | `/zh` 加原路径 |
| 成员、邀请、设置、站点管理 | 原路径 | `/zh` 加原路径 |
| 产品 RSS | `/rss.xml` | `/zh/rss.xml` |
| 模板官网 | 原路径 | `/zh` 加原路径 |
| 核心教程 | `/en/agentbuff-stack/` | `/agentbuff-stack/` |

API、认证签名入口、私有文件下载和 `/_app/` 资产始终使用根路径。未知功能不会因为加上 `/zh` 就存在。关闭中文后，公开页不再生成，边缘也不将中文路径交给工作台。

| 文案或规则 | 位置 |
| --- | --- |
| 产品说明与方案描述 | `packages/core/website.ts` |
| 语言登记与路由 | `packages/core/locales.ts`、`routing.ts` |
| 公开页与功能文案 | `apps/web/lib/locales/en.ts`、`zh.ts`、`es.ts` |
| 工具名、步骤与完整 FAQ | `packages/core/tool-locales.ts` |
| 推荐、营销同意及申请界面 | `packages/core/referral-copy.ts`、`marketing.ts`、`apps/web/lib/marketing-copy.ts` |
| 工作台完整字典及稳定错误码 | `apps/app/lib/locales/`、`locale-errors.ts` |
| 邮件主题、预览与正文 | `apps/email/locales.ts` |
| 请求语言的服务器选择 | `apps/api/lib/email-locale.ts` |
| 产品文章目录与校验 | `apps/web/lib/posts.ts`、`blog-catalogue.ts` |
| 独立官网字典与模块 | `apps/website/lib/i18n.ts`、`modules.ts` |
| 核心英文教程与教程界面 | `docs/en/agentbuff-stack/`、`docs/.vitepress/` |

双语共用页面组件与业务逻辑，中文字典按英文字典类型校验。原始输入、代码、品牌、标识、金额、密钥、审计原因和历史流水备注不翻译。日期与金额的展示使用所选语言，不修改权威数值。

## 切换与登录回跳

公开语言菜单只链接当前页面真实存在的版本，并提供对应规范链接、语言替代标记和站点地图。公开切换不复制任意查询参数或令牌。

工具切换语言会重新加载，应先复制尚未保存的输入。匿名保存时，输入暂存在当前标签页，安全登录后返回同语言同工具恢复预览，不自动保存。存储不可用时会保留页面提示，不丢弃输入后跳走。

工作台只有一份路由树。地址改写保留支持的任务或购买标识、查询及片段，并同步调整安全 `returnTo`。密码、验证码、注册验证、第三方回调及密码重置沿用所选受支持路径。语言不影响账号、团队、权限、积分或执行次数。

## 博客与缺译文

产品英文原稿在 `apps/web/content/blog/*.md`，中文在 `zh/`，文件名相同。标题、简介、分类和正文都必须完整；保留示例代码及原数据，内部链接指向实际语言版本。作者、发布日期、更新日期和事实应一起核对。

英文草稿不发布任何译文。中文缺失或为草稿时，中文列表不偷偷混入英文，也不产生中文详情、RSS 条目或替代链接。空正文、孤立译文、无效日期、未知工具会拒绝构建。可选西语保留原有明确标注的英文回退。

官网内容独立放在 `apps/website/content/`，使用 `locale` 与稳定的 `translationKey` 配对，不读取产品文章。案例应是基于模板建成的独立站，演示内工具不算案例。

## 邮件与托管支付

即时认证邮件按请求中已启用语言选择，未知或停用值回退英文。营销请求保存当时展示的同意文案及语言；任务邮件偏好保存用户主动选择的语言。后续切换页面或重启不会更改已排队请求的语言和载荷。停用语言会停止新投递，但保留历史撤回入口；旧未保存语言的邮件沿用原兼容载荷。

积分包和订阅保存原支付请求的语言及回站路径。同键重试保留原选择，换语言不能借同键建立另一次支付。中文支付配置与模板流程可本地检查，真实供应商页面、真实付款和送达仍需独立验收。

现有语言字段是文本，但邮件、营销和积分购买有语言检查约束。新增 `0035_chinese_locales.sql` 仅放宽对应约束，保留原值和旧请求；启用相关中文持久化模块前需在已核实的目标库完整升级。主预览维持已授权的 0012 水平；通知、营销、推广等可选表不因翻译自动升级。

## 教程界面与历史

中文教程保留原网址，英文核心指南在 `/en/`。核心页正文上方提供对应语言链接；全局语言菜单回到对应语言首页，避免历史中文页切出不存在的英文网址。搜索、目录、页尾、主题切换及复制提示随教程语言变化。

英文目录中的历史链接明确标注中文，历史验收内容不改写。译文根据现有文案编写，适配真实产品时应复核业务说明、隐私草案及措辞。未完成的真实服务验收仍如实保留。

## 本地核对

检查两种语言的主页面、移动菜单、主题、键盘焦点、工具输入输出和登录回跳；检查实际文章正文、分类搜索、RSS、规范与替代链接；验证关闭语言、缺译文及草稿不会产生虚假页面。邮件与支付测试使用捕获器及隔离测试数据，不接真实产品或发布云端。