Better i18n/帮助中心

常见问题

查找常见问题的答案

快速入门

发布翻译后需要重新构建应用吗？

不需要。Better i18n 通过全球 CDN 在运行时提供翻译内容。当您发布后，无需任何重新构建或重新部署，您的应用在 ~60 秒内即可获得最新翻译。SDK 会自动获取最新的翻译内容。

如果 CDN 宕机会发生什么？

CDN 被设计为始终返回 HTTP 200 — 即使在出现错误时，您的应用也会收到 {} 或 { "fallback": true }，而不是失败响应。

SDK 具有 5 层回退链：

  1. 内存缓存（TtlCache，60秒 TTL）
  2. CDN 请求（带超时 + 重试）
  3. 持久化存储（如已配置 — 例如移动端的 AsyncStorage）
  4. 静态回退数据（您提供的打包翻译）
  5. 错误（仅在所有层都失败时）

实际上，由于缓存或静态数据始终可用，用户几乎不会遇到失败情况。

有免费计划吗？

有！Better i18n 提供免费套餐，包括：

  • 1 个项目
  • 无限翻译键
  • AI 翻译积分
  • CDN 分发
  • CLI 访问

付费计划可添加更多项目、团队成员、高级功能和更高的使用限制。请查看定价页面了解当前详情。

Better i18n 支持从右到左（RTL）语言吗？

Better i18n 是一个字符串分发平台 — 无论文字方向如何，它都能存储和传递翻译字符串。阿拉伯语、希伯来语和波斯语等 RTL 语言完全支持作为翻译目标。

但是，RTL 布局和 CSS（如 direction: rtl、镜像界面）是您应用程序的责任。SDK 负责传递正确的翻译字符串；您的 CSS 框架处理视觉方向。

管理翻译

AI 翻译需要多长时间？

AI 翻译速度取决于内容量：

键数量 大约时间
1–50 几秒钟
50–500 不到1分钟
500–1000 1–3分钟
1000+ 3–5分钟

翻译以并行批次运行，因此扩展性很好。翻译进行期间您可以继续在控制台中工作。

我可以使用人工翻译而不是 AI 吗？

当然可以。您可以：

  • 邀请翻译人员 — 使用 Translator 角色，他们可以访问专注的翻译界面
  • 使用审核队列 — 翻译人员可以审核、编辑和批准翻译
  • 结合 AI + 人工 — 使用 AI 进行初次翻译，然后由人工翻译人员审核和完善

Translator 角色只能访问翻译编辑功能，无法访问项目设置或键管理。

什么是命名空间（namespace）？

命名空间是翻译键的逻辑分组。例如：

  • common — 共享字符串，如「保存」、「取消」、「加载中」
  • auth — 登录/注册相关字符串
  • dashboard — 控制台专用字符串

命名空间支持按需加载 — 您的应用只获取当前页面所需的翻译。它们还有助于在大型项目中组织键并减少冲突。

在代码中，您可以这样引用命名空间：t('common:save_button') 或 useTranslations('common')。

翻译可以回滚吗？

可以。每次发布都会创建您翻译的快照。如果出了问题：

  1. 进入您项目的发布历史
  2. 找到上一个正常的发布版本
  3. 点击回滚

这会将 CDN 恢复到所选快照。您的应用将在 ~60 秒内提供回滚后的翻译。

开发者集成

我应该使用单例还是多个 SDK 实例？

始终使用单例 — 在模块作用域创建一个 SDK 实例并在各处复用。

SDK 的 TtlCache 是一个模块级全局变量，在同一进程中的所有 createI18nCore() 实例之间共享。创建多个实例是浪费的但无害 — 它们会共享同一个缓存。

// ✅ 推荐 — 模块级单例
export const i18n = createI18n({ project: 'acme/dashboard', ... });

// ❌ 避免 — 在组件/处理函数内创建
function handler() {
  const i18n = createI18n({ ... }); // 每个请求创建新实例
}
org/project 格式是什么？

项目标识符使用 org/project 格式，例如 acme/dashboard。这直接映射到 CDN URL：

https://cdn.better-i18n.com/acme/dashboard/manifest.json
https://cdn.better-i18n.com/acme/dashboard/en/translations.json
  • org — 您的组织 slug（注册时设置）
  • project — 项目 slug（创建项目时设置）

此格式在各处使用：SDK 配置、CLI 配置、API 调用和 CDN URL。区分大小写。

SDK 可以在边缘运行时上运行吗？

可以。SDK 仅使用标准 Fetch API — 不需要任何 Node.js 内置模块（fs、path、crypto 等）。这意味着它可以在以下平台运行：

  • Cloudflare Workers
  • Vercel Edge Functions
  • Deno Deploy
  • Bun
  • 任何符合 Web 标准的运行时

唯一的要求是一个全局 fetch 函数。如果需要，您也可以通过 fetch 配置选项传入自定义 fetch。

CLI 和 SDK 有什么区别？

它们服务于不同目的：

CLI (@better-i18n/cli) SDK (@better-i18n/next，等)
何时 开发时 运行时
目的 扫描代码、同步键、检查状态 获取和显示翻译
运行在 您的机器 / CI 您的应用（浏览器、服务器、移动端）
认证 密钥 (sk_...) 公钥或无
安装 全局或 devDependency Dependency

CLI 管理您的翻译键。SDK 将它们传递给用户。

故障排除与常见问题

如何检查 CDN 是否正常运行？

直接获取您的翻译来验证 CDN 健康状况：

# 检查 manifest
curl -w '\nHTTP %{http_code} | Time: %{time_total}s\n' \
  https://cdn.better-i18n.com/your-org/your-project/manifest.json

# 检查翻译
curl -w '\nHTTP %{http_code} | Time: %{time_total}s\n' \
  https://cdn.better-i18n.com/your-org/your-project/en/translations.json

CDN 始终返回 HTTP 200。检查响应主体：

  • 包含您翻译的有效 JSON → CDN 正常
  • {} 或 { "fallback": true } → 翻译尚未发布
  • 响应时间 > 1s → 可能存在网络问题（正常为 <100ms）
为什么我的应用显示的是回退语言而不是用户的语言？

四种常见原因：

  1. 语言未发布 — 检查控制台中该语言的翻译是否存在并已发布
  2. 语言区域标识化不匹配 — CDN 使用小写 BCP 47（pt-br），但您的应用可能发送 pt-BR。使用 @better-i18n/core 中的 normalizeLocale()
  3. 中间件未检测语言区域 — 检查您的中间件配置，确保已配置 Accept-Language 头匹配
  4. Manifest 中缺少该语言区域 — CDN manifest 列出可用语言区域。如果您的语言区域不在其中，SDK 会回退到默认语言区域

通过检查 manifest 进行验证：

curl https://cdn.better-i18n.com/your-org/your-project/manifest.json

响应应列出所有已发布的语言区域。

AI 与自动化

AI 翻译对于生产环境是否足够准确？

对于大多数内容，是的。AI 翻译质量取决于几个因素：

  • 上下文 — 带有上下文注释的键翻译效果明显更好
  • 词汇表 — 强制执行一致的术语可消除最常见的错误
  • 内容类型 — UI 字符串、标签和简短描述翻译效果非常好。营销文案和创意内容可能需要人工审核

推荐方法：使用 AI 进行初次翻译，然后让母语人士审核关键的面向用户内容。审核队列使这个工作流程变得简单。

翻译使用了哪些 AI 模型？

Better i18n 使用多种针对翻译质量优化的大型语言模型组合。平台根据内容类型和语言对自动选择最佳模型。

您无需选择或配置模型 — 平台会为您处理。模型选择会根据翻译质量指标持续优化。

哪些 AI 编码代理可以与 MCP 服务器配合使用？

任何兼容 MCP 的代理都可以与 Better i18n MCP 服务器配合使用，包括：

  • Claude Code（CLI）— 完全支持
  • Claude Desktop — 完全支持
  • Cursor — 通过 MCP 设置
  • Windsurf — 通过 MCP 设置
  • Continue — 通过 MCP 配置
  • 自定义代理 — 任何使用 MCP SDK 构建的代理

MCP 服务器提供用于管理翻译键、翻译、发布和内容管理的工具。代理通过自然语言命令调用这些工具。

内容管理

翻译键与 Content SDK 有什么区别？

它们服务于不同的使用场景：

翻译键 Content SDK
用于 短 UI 字符串 结构化富文本内容
示例 按鈕标签、错误消息、页面标题 博客文章、更日志、帮助文章
格式 键值对 带有类型字段的内容模型
编辑 控制台翻译编辑器 控制台内容编辑器（Markdown）
分发 通过 SDK 的 CDN 通过 @better-i18n/sdk 的内容 API

使用翻译键处理 UI 文本。使用 Content SDK 处理具有标题、正文、元数据和关联的结构化内容。

Content SDK 有请求频率限制吗？

有，频率限制取决于您的计划套餐。API 返回标准频率限制头部：

  • X-RateLimit-Limit — 每个时间窗口内允许的请求数
  • X-RateLimit-Remaining — 剩余请求数
  • X-RateLimit-Reset — 时间窗口重置时间（Unix 时间戳）

如果超过限制，API 返回 HTTP 429。SDK 不会在频率限制时自动重试 — 如果您发出大量请求，请在应用中自行处理。

对于大多数应用程序，频率限制已足够宽松。服务器端缓存（如帮助中心应用中使用的）进一步减少 API 调用次数。

团队与账户

我可以有多少个项目？

项目数量取决于您的计划套餐：

  • 免费 — 1 个项目
  • Pro — 多个项目（请查看定价页面了解当前限制）
  • 企业版 — 无限项目

每个项目完全独立，拥有自己的键、语言、团队成员和发布历史。请查看定价页面了解当前详情。

翻译人员能看到我组织中的所有项目吗？

不能。团队成员是按项目分配的。被邀请到“项目 A”的翻译人员无法看到“项目 B”，除非被明确添加。

这样您可以：

  • 邀请外部翻译人员负责特定项目，而不暴露其他项目
  • 为不同项目分配不同的翻译人员
  • 在整个组织中精细控制访问权限