我的翻译没有显示——应该检查什么？
如果应用显示原始键名或某些语言的翻译缺失，请按照此检查清单逐步排查问题。
7 分钟阅读中级
如果应用显示原始键名（如 common.welcome_title）而非翻译文本，或某些语言的翻译缺失，请按此清单逐步排查。
第一步：翻译是否已发布？
最常见的原因是翻译未发布。检查您的控制台：
- 进入您的项目
- 查找 "草稿更改" 指示器
- 如果有未发布的更改，点击 "发布"
只有已发布的翻译才能在 CDN 上使用。草稿翻译仅在控制台中可见。
第二步：直接检查 CDN
通过直接获取来验证翻译是否在 CDN 上：
# 检查 manifest（可用 locale 列表）
curl https://cdn.better-i18n.com/your-org/your-project/manifest.json
# 检查特定 locale 的翻译
curl https://cdn.better-i18n.com/your-org/your-project/en/translations.json
如果 manifest 返回空对象或 { "fallback": true }，说明翻译尚未发布。
第三步：验证项目配置
确保 SDK 配置与您的项目匹配：
// 再次检查项目标识符
const i18n = createI18n({
project: 'acme/dashboard', // 必须完全匹配：org/project
defaultLocale: 'en', // 必须与源 locale 匹配
});
常见错误：
org/project格式错误（区分大小写）defaultLocale与控制台中的源语言不匹配- 在需要公钥的地方使用了密钥（或反之）
第四步：检查 locale 标准化
CDN 使用小写 BCP 47 locale 代码。如果应用使用 pt-BR 而 CDN 期望 pt-br，翻译将无法匹配。
SDK 通过 normalizeLocale() 自动处理此问题，但如果您手动构建 URL，请确保将其转换为小写。
第五步：检查浏览器控制台
打开 DevTools 并查找：
- Network 标签页 — 是否有对
cdn.better-i18n.com的请求？响应是什么？ - 控制台错误 — 是否有类似
BETTER_I18N_PROJECT is not configured的错误？ - 响应正文 — 翻译 JSON 是否包含您的键名？
第六步：缓存时间
发布后，缓存可能会在短暂窗口内提供陈旧数据：
| 缓存层 | 最大陈旧时间 |
|---|---|
| CDN 边缘 | 发布时立即清除 |
SDK 内存缓存（TtlCache） |
最多 60 秒 |
| Next.js ISR | 最多 30 秒（默认） |
| 浏览器 HTTP 缓存 | 最多 60 秒 |
发布后等待 60 秒并强制刷新浏览器（Cmd+Shift+R）。
第七步：检查命名空间匹配
如果使用命名空间，请确保代码与控制台之间保持一致：
// 代码使用 'common' 命名空间
const t = useTranslations('common');
// 控制台中必须在 'common' 命名空间下有对应键名
// common.welcome_title → "欢迎！"
如果键名在默认命名空间中，但代码请求特定命名空间（或反之），翻译将无法解析。
仍然卡住了？
运行 CLI doctor 命令：
better-i18n doctor
这将检查配置、身份验证、API 连接以及常见的配置问题。