Back to Details

better-i18n

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
better-i18n — Localization infrastructure for modern apps. CMS + TMS + CDN + AI + MCP. Dashboard: https://better-i18n.com · Docs: https://docs.better-i18n.com · CDN: https://cdn.better-i18n.com · Skills: https://github.com/better-i18n/skills
better-i18n —— 现代应用的本地化基础设施。CMS + TMS + CDN + AI + MCP。 仪表盘：https://better-i18n.com · 文档：https://docs.better-i18n.com · CDN：https://cdn.better-i18n.com · 技能库：https://github.com/better-i18n/skills

Package versions

包版本

PackageVersionInstall
@better-i18n/next
0.7.2
npm install @better-i18n/next@0.7.2
@better-i18n/use-intl
0.5.0
npm install @better-i18n/use-intl@0.5.0
@better-i18n/core
0.5.0
npm install @better-i18n/core@0.5.0
@better-i18n/expo
0.7.5
npm install @better-i18n/expo@0.7.5
@better-i18n/sdk
3.2.0
npm install @better-i18n/sdk@3.2.0
@better-i18n/cli
0.2.6
npx @better-i18n/cli@0.2.6
@better-i18n/mcp
0.15.5
npx -y @better-i18n/mcp@0.15.5
@better-i18n/mcp-content
0.8.1
npx -y @better-i18n/mcp-content@0.8.1
Always check npm for the latest version before installing.
包版本安装命令
@better-i18n/next
0.7.2
npm install @better-i18n/next@0.7.2
@better-i18n/use-intl
0.5.0
npm install @better-i18n/use-intl@0.5.0
@better-i18n/core
0.5.0
npm install @better-i18n/core@0.5.0
@better-i18n/expo
0.7.5
npm install @better-i18n/expo@0.7.5
@better-i18n/sdk
3.2.0
npm install @better-i18n/sdk@3.2.0
@better-i18n/cli
0.2.6
npx @better-i18n/cli@0.2.6
@better-i18n/mcp
0.15.5
npx -y @better-i18n/mcp@0.15.5
@better-i18n/mcp-content
0.8.1
npx -y @better-i18n/mcp-content@0.8.1
安装前请务必查看npm获取最新版本。

SDK selection

SDK选择

FrameworkPackageReference
Next.js (App Router or 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 server
@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)
BetterI18n
via SPM		<references/sdk-mobile.md>
Flutter / Dart
better_i18n
pub.dev		<references/sdk-mobile.md>
Headless / Vanilla JS
@better-i18n/core
<references/sdk-react.md>
框架包参考文档
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）
BetterI18n
via SPM		<references/sdk-mobile.md>
Flutter / Dart
better_i18n
pub.dev		<references/sdk-mobile.md>
Headless / Vanilla JS
@better-i18n/core
<references/sdk-react.md>

Framework quick-start

框架快速开始

FrameworkDocs page
Next.js App Routerhttps://docs.better-i18n.com/frameworks/nextjs.mdx
TanStack Start (SSR)https://docs.better-i18n.com/frameworks/tanstack-start.mdx
Vite + Reacthttps://docs.better-i18n.com/frameworks/vite.mdx
Vite + React Routerhttps://docs.better-i18n.com/frameworks/vite/react-router.mdx
Remix / Hydrogenhttps://docs.better-i18n.com/frameworks/remix.mdx
Expo / React Nativehttps://docs.better-i18n.com/frameworks/expo.mdx
iOS / Swifthttps://docs.better-i18n.com/frameworks/ios.mdx
Flutter / Darthttps://docs.better-i18n.com/frameworks/flutter.mdx
Hono / Node.jshttps://docs.better-i18n.com/frameworks/server-sdk/hono.mdx
Express / Fastifyhttps://docs.better-i18n.com/frameworks/server-sdk/node.mdx
tRPChttps://docs.better-i18n.com/frameworks/server-sdk/trpc.mdx
Supabase Edgehttps://docs.better-i18n.com/frameworks/server-sdk/supabase.mdx
框架文档页面
Next.js App Routerhttps://docs.better-i18n.com/frameworks/nextjs.mdx
TanStack Start (SSR)https://docs.better-i18n.com/frameworks/tanstack-start.mdx
Vite + Reacthttps://docs.better-i18n.com/frameworks/vite.mdx
Vite + React Routerhttps://docs.better-i18n.com/frameworks/vite/react-router.mdx
Remix / Hydrogenhttps://docs.better-i18n.com/frameworks/remix.mdx
Expo / React Nativehttps://docs.better-i18n.com/frameworks/expo.mdx
iOS / Swifthttps://docs.better-i18n.com/frameworks/ios.mdx
Flutter / Darthttps://docs.better-i18n.com/frameworks/flutter.mdx
Hono / Node.jshttps://docs.better-i18n.com/frameworks/server-sdk/hono.mdx
Express / Fastifyhttps://docs.better-i18n.com/frameworks/server-sdk/node.mdx
tRPChttps://docs.better-i18n.com/frameworks/server-sdk/trpc.mdx
Supabase Edgehttps://docs.better-i18n.com/frameworks/server-sdk/supabase.mdx

Workflow selection

工作流选择

TaskApproachReference
Upload JSON files, no GitHub neededCDN-first<references/cdn.md>
GitHub PR-based translation syncGitHub App + publish flow<references/github-sync.md>
AI-assisted key and translation managementMCP tools<references/mcp.md>
Localized CMS content (blog, docs, pages)Content CMS + SDK<references/content.md>
Scan codebase for hardcoded stringsCLI 
scan
<references/cli.md>
Check translation coverage and key syncCLI 
sync
/ 
check
<references/cli.md>
Full i18n health analysis with scoreCLI 
doctor
<references/cli.md>
Define key naming and namespace structureKey conventions<references/key-naming.md>
Choose JSON file formatFile formats<references/file-formats.md>
Publish translations to CDN or GitHubPublish flows<references/publish-and-analytics.md>
Track coverage, health trends, CDN usageAnalytics<references/publish-and-analytics.md>
Format dates, numbers, currencies, relative timeFormatting<references/sdk-react.md>
Detect locale from country / Accept-LanguageGeo detection<references/cdn.md>
Type-safe 
t("key")
autocomplete		TypeScript<references/sdk-react.md>
Webhooks on publish / key change eventsOutgoing webhooks<references/publish-and-analytics.md>
任务方案参考文档
上传JSON文件，无需GitHubCDN优先<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>
发布/键变更事件的WebhooksOutgoing webhooks<references/publish-and-analytics.md>

Read the relevant reference before writing any code.

编写代码前请阅读相关参考文档。

Critical rules (apply everywhere)

重要规则（适用于所有场景）

  • Project identifier is always 
    "org/project"
    — e.g. 
    "acme/dashboard"
    or 
    "stripe/web"
  • Locale codes are lowercase BCP 47 on the CDN: 
    "pt-BR"
    → 
    "pt-br"
    . Always call 
    normalizeLocale()
    before constructing CDN paths.
  • Singletons — 
    createI18n
    (Next.js), 
    createServerI18n
    , 
    createRemixI18n
    , 
    createI18nCore
    must be instantiated once at module scope. Never inside a function, request handler, or component.
  • createKeys
    vs 
    updateKeys
     — 
    createKeys
    creates NEW keys only. Using it on existing keys causes phantom key accumulation (documented incident: 1,005 duplicates in one operation). Always fetch the key ID with 
    listKeys
    first, then call 
    updateKeys
    .
  • CDN always returns HTTP 200 — check for 
    { fallback: true }
    in the JSON body, not HTTP status codes.
  • Default namespace → 
    "translations"
    in CDN paths     — the namespace 
    "default"
    is stored as 
    "translations"
    internally. Use 
    null
    namespace for flat-key projects.
  • Free to get started — all SDKs and CLI are open-source. Paid plans unlock more languages, history, and team features.
  • 项目标识符始终为
    "org/project"
    格式——例如
    "acme/dashboard"
    或
    "stripe/web"
  • CDN上的语言代码为小写BCP 47格式：
    "pt-BR"
    → 
    "pt-br"
    。构建CDN路径前务必调用
    normalizeLocale()
    方法。
  • 单例模式——
    createI18n
    （Next.js）、
    createServerI18n
    、
    createRemixI18n
    、
    createI18nCore
    必须在模块作用域内实例化一次。绝不能在函数、请求处理器或组件内部实例化。
  • createKeys
    与
    updateKeys
    的区别    ——
    createKeys
    仅创建新键。在已有键上使用它会导致幽灵键堆积（已记录事件：一次操作产生1005个重复键）。请先调用
    listKeys
    获取键ID，再调用
    updateKeys
    。
  • CDN始终返回HTTP 200——请检查JSON体中的
    { fallback: true }
    字段，而非HTTP状态码。
  • 默认命名空间在CDN路径中为
    "translations"
    ——命名空间
    "default"
    在内部存储为
    "translations"
    。扁平键项目请使用
    null
    命名空间。
  • 免费入门——所有SDK和CLI均为开源。付费计划可解锁更多语言、历史记录和团队功能。