i18n-best-practices

Original：🇺🇸 English

Translated

Use when building internationalization features, managing translation keys, setting up localization workflows, integrating AI translation, connecting GitHub repositories, delivering translations via CDN, using MCP tools for translation management, or implementing i18n SDKs in React/Next.js applications.

1installs

Sourcebetter-i18n/skills

Added on2026-02-10

NPX Install

npx skill4agent add better-i18n/skills i18n-best-practices

SKILL.md Content

View Translation Comparison →

i18n Best Practices

Guidance for building scalable, maintainable internationalization systems with 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

CDN URL Structure

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

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

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.

URL Strategy

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.

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