i18n-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

i18n Best Practices

国际化（i18n）最佳实践

Guidance for building scalable, maintainable internationalization systems with Better i18n.

本指南介绍如何借助Better i18n构建可扩展、易维护的国际化系统。

Architecture Overview

架构概述

Better i18n is a GitHub-first localization platform with CDN-powered delivery:

[Your Repository] → [Better i18n Platform] → [Global CDN] → [Your App]
        ↓                    ↓                    ↓              ↓
   AST Parsing          AI Translation       Edge Cached    React/Next.js
   Key Discovery        Human Approval       5min manifest  Vite/TanStack
   GitHub Sync          MCP Tools            1hr messages   Any Framework

Better i18n是一个以GitHub为核心的本地化平台，支持基于CDN的内容交付：

[你的代码仓库] → [Better i18n平台] → [全球CDN] → [你的应用]
        ↓                    ↓                    ↓              ↓
   AST语法解析          AI翻译           边缘缓存     React/Next.js
   翻译键识别          人工审核        5分钟清单缓存  Vite/TanStack
   GitHub同步          MCP工具         1小时消息缓存  任意框架

CDN URL Structure

CDN URL结构

https://cdn.better-i18n.com/{org}/{project}/{resource}

Resources:
├── manifest.json              # Available languages + metadata
├── {locale}.json              # All translations for locale
├── {locale}/{namespace}.json  # Namespaced translations
└── flags/{code}.svg           # Country flag images

https://cdn.better-i18n.com/{org}/{project}/{resource}

资源说明：
├── manifest.json              # 可用语言及元数据
├── {locale}.json              # 该语言的全部翻译内容
├── {locale}/{namespace}.json  # 按命名空间划分的翻译内容
└── flags/{code}.svg           # 国家/地区旗帜图片

Quick Reference

快速参考

Need to...	See
Set up a new i18n project	Getting Started
Use CLI commands (scan, check, sync)	CLI Usage
Organize translation keys and namespaces	Key Management
Translate content with AI assistance	AI Translation
Sync translations with GitHub repository	GitHub Sync
Serve translations via CDN	CDN Delivery
Use MCP tools in your IDE/agent	MCP Integration
Integrate with React or Next.js	SDK Integration
Handle plurals, dates, formatting	Best Practices

需求	查看文档
搭建新的i18n项目	快速入门
使用CLI命令（扫描、检查、同步）	CLI使用指南
管理翻译键与命名空间	翻译键管理
借助AI辅助翻译内容	AI翻译
与GitHub仓库同步翻译内容	GitHub同步
通过CDN提供翻译内容	CDN交付
在IDE/Agent中使用MCP工具	MCP集成
集成到React或Next.js	SDK集成
处理复数、日期、格式化	最佳实践

Start Here

入门指引

New project? Start with Getting Started to create your project and configure

i18n.config.ts

. Then use CLI Usage to scan your codebase for hardcoded strings.

Existing codebase with hardcoded strings? Run

better-i18n scan

to detect strings needing translation. The CLI uses AST parsing to automatically differentiate UI text from developer symbols. See CLI Usage.

Need translations fast? Use AI Translation to translate content with context-aware AI. Set up a glossary first to ensure consistent terminology across all translations.

Building with Next.js? Use

@better-i18n/next

which integrates with

next-intl

. Supports ISR, middleware with auth callbacks, and automatic CDN fetching. See SDK Integration.

Building with Vite/TanStack Start? Use

@better-i18n/use-intl

for React hooks or full SSR support with TanStack Start. See SDK Integration.

Using AI coding assistants (Claude, Cursor)? Install the MCP server via MCP Integration. Your agent can create, update, delete keys and add languages directly from your IDE.

Production deployment? Set up CDN Delivery for edge-cached translations. Manifest caches for 5 minutes, messages for 1 hour. Combine with GitHub Sync for version-controlled deployments.

CI/CD integration? Use

better-i18n check:missing

in your pipeline to fail builds when translations are incomplete. See CLI Usage.

新项目？ 从快速入门开始，创建项目并配置

i18n.config.ts

。然后使用CLI使用指南扫描代码库，找出硬编码的字符串。

已有代码库包含硬编码字符串？ 运行

better-i18n scan

命令检测需要翻译的字符串。CLI会通过AST语法解析自动区分UI文本与开发者符号。详情请见CLI使用指南。

需要快速完成翻译？ 使用AI翻译借助上下文感知AI完成翻译。建议先创建术语表，确保所有翻译内容的术语一致性。

基于Next.js开发？ 使用

@better-i18n/next

包，它与

next-intl

集成，支持增量静态再生（ISR）、带认证回调的中间件，以及自动从CDN拉取内容。详情请见SDK集成。

基于Vite/TanStack Start开发？ 使用

@better-i18n/use-intl

获取React Hooks，或在TanStack Start中实现完整的SSR支持。详情请见SDK集成。

使用AI编码助手（Claude、Cursor）？ 通过MCP集成安装MCP服务器。你的Agent可以直接在IDE中创建、更新、删除翻译键，以及添加新语言。

生产环境部署？ 配置CDN交付实现边缘缓存的翻译内容。清单缓存有效期为5分钟，消息缓存为1小时。结合GitHub同步实现版本控制的部署流程。

CI/CD集成？ 在流水线中使用

better-i18n check:missing

命令，当翻译内容不完整时触发构建失败。详情请见CLI使用指南。

URL Strategy

URL策略

Better i18n uses default locale without prefix for SEO:

/about          → English (default)
/tr/about       → Turkish
/de/about       → German

Clean URLs for primary language, SEO-friendly variants with proper

hreflang

tags for others.

Better i18n采用默认语言不带前缀的策略以优化SEO：

/about          → 英文（默认语言）
/tr/about       → 土耳其语
/de/about       → 德语

主语言使用简洁URL，其他语言使用带语言前缀的SEO友好变体，并配置正确的

hreflang

标签。

Caching Strategy

缓存策略

Resource	Browser Cache	CDN Cache	Invalidation
Manifest	5 minutes	5 minutes	On publish
Messages	1 hour	1 hour	On publish
Flags	1 year	1 year	Immutable

资源	浏览器缓存	CDN缓存	失效机制
清单（Manifest）	5分钟	5分钟	发布时失效
消息（Messages）	1小时	1小时	发布时失效
旗帜图片（Flags）	1年	1年	不可变（永久缓存）