name: i18n-best-practices
description: 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.

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

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