better-i18n

better-i18n — 面向现代应用的本地化基础设施。CMS + TMS + CDN + AI + MCP。 控制台：https://better-i18n.com · 文档：https://docs.better-i18n.com · CDN：https://cdn.better-i18n.com · Skills：https://github.com/better-i18n/skills

软件包版本

软件包	版本	安装
@better-i18n/next	0.7.2	npm install @better-i18n/[email protected]
@better-i18n/use-intl	0.5.0	npm install @better-i18n/[email protected]
@better-i18n/core	0.5.0	npm install @better-i18n/[email protected]
@better-i18n/expo	0.7.5	npm install @better-i18n/[email protected]
@better-i18n/sdk	3.2.0	npm install @better-i18n/[email protected]
@better-i18n/cli	0.2.6	npx @better-i18n/[email protected]
@better-i18n/mcp	0.15.5	npx -y @better-i18n/[email protected]
@better-i18n/mcp-content	0.8.1	npx -y @better-i18n/[email protected]

安装前请务必在 npm 上查看最新版本。

SDK 选择

框架	软件包	参考文档
Next.js（App Router 或 Pages Router）	@better-i18n/next	<references/sdk-next.md>
React + TanStack Router / use-intl	@better-i18n/use-intl	<references/sdk-react.md>
Hono / Node.js 服务	@better-i18n/server	<references/sdk-react.md>
Remix / Shopify Hydrogen	@better-i18n/remix	<references/sdk-react.md>
React Native / Expo	@better-i18n/expo	<references/sdk-mobile.md>
Swift（iOS / macOS / visionOS）	通过 SPM 使用 BetterI18n	<references/sdk-mobile.md>
Flutter / Dart	better_i18n pub.dev	<references/sdk-mobile.md>
无头 / Vanilla JS	@better-i18n/core	<references/sdk-react.md>

框架快速入门

框架	文档页面
Next.js App Router	https://docs.better-i18n.com/frameworks/nextjs.mdx
TanStack Start（SSR）	https://docs.better-i18n.com/frameworks/tanstack-start.mdx
Vite + React	https://docs.better-i18n.com/frameworks/vite.mdx
Vite + React Router	https://docs.better-i18n.com/frameworks/vite/react-router.mdx
Remix / Hydrogen	https://docs.better-i18n.com/frameworks/remix.mdx
Expo / React Native	https://docs.better-i18n.com/frameworks/expo.mdx
iOS / Swift	https://docs.better-i18n.com/frameworks/ios.mdx
Flutter / Dart	https://docs.better-i18n.com/frameworks/flutter.mdx
Hono / Node.js	https://docs.better-i18n.com/frameworks/server-sdk/hono.mdx
Express / Fastify	https://docs.better-i18n.com/frameworks/server-sdk/node.mdx
tRPC	https://docs.better-i18n.com/frameworks/server-sdk/trpc.mdx
Supabase Edge	https://docs.better-i18n.com/frameworks/server-sdk/supabase.mdx

工作流选择

任务	方案	参考
上传 JSON 文件，无需 GitHub	CDN 优先	<references/cdn.md>
基于 GitHub PR 同步翻译	GitHub App + 发布流程	<references/github-sync.md>
借助 AI 管理键和翻译	MCP 工具	<references/mcp.md>
本地化 CMS 内容（博客、文档、页面）	内容 CMS + SDK	<references/content.md>
扫描代码库中的硬编码字符串	CLI scan	<references/cli.md>
检查翻译覆盖率和键同步情况	CLI sync / check	<references/cli.md>
全面分析 i18n 健康状况并评分	CLI doctor	<references/cli.md>
定义键命名和命名空间结构	键约定	<references/key-naming.md>
选择 JSON 文件格式	文件格式	<references/file-formats.md>
将翻译发布到 CDN 或 GitHub	发布流程	<references/publish-and-analytics.md>
跟踪覆盖率、健康趋势、CDN 用量	分析	<references/publish-and-analytics.md>
格式化日期、数字、货币、相对时间	格式化	<references/sdk-react.md>
根据国家/地区或 Accept-Language 检测区域设置	地理位置检测	<references/cdn.md>
类型安全的 t("key") 自动补全	TypeScript	<references/sdk-react.md>
在发布/键变更事件发生时触发 Webhook	出站 Webhook	<references/publish-and-analytics.md>

编写任何代码前，请先阅读相关参考资料。

关键规则（适用于所有场景）

• 项目标识符始终为 "org/project"，例如 "acme/dashboard" 或 "stripe/web"
• CDN 上的区域设置代码采用小写 BCP 47 格式："pt-BR" → "pt-br"。构建 CDN 路径前务必调用 normalizeLocale()。
• 单例——createI18n（Next.js）、createServerI18n、createRemixI18n、createI18nCore 必须在模块作用域中实例化一次。切勿在函数、请求处理程序或组件内实例化。
• createKeys 与 updateKeys——createKeys 只会创建新键。对现有键使用它会导致虚假键不断累积（有记录的事故：一次操作中产生 1,005 个重复键）。务必先通过 listKeys 获取键 ID，再调用 updateKeys。
• CDN 始终返回 HTTP 200——检查 JSON 正文中的 { fallback: true }，而不是 HTTP 状态码。
• CDN 路径中的默认命名空间 → "translations"——命名空间 "default" 在内部存储为 "translations"。对于扁平键项目，请使用 null 命名空间。
• 免费开始使用——所有 SDK 和 CLI 均为开源。付费方案可解锁更多语言、历史记录和团队功能。