Better i18n

What is Better i18n about?

Better i18n provides a set of TypeScript‑first SDKs and a CLI that let developers synchronize, translate, and serve localization data directly from GitHub, a CDN edge network, and AI translation models. The ecosystem covers Next.js, generic React, and Expo/React Native, and includes an MCP server for AI agents to interact with the translation workflow.

How to use Better i18n?

1. Install the CLI

   npm install -g @better-i18n/cli
   

2. Initialize a project

   npx @better-i18n/cli init
   

3. Scan source files for translation keys

   npx @better-i18n/cli scan
   

4. Sync keys and translations with the Better i18n platform

   npx @better-i18n/cli sync
   

5. Add the appropriate SDK (example for Next.js):

   npm install @better-i18n/next
   

   Then configure the middleware as shown in the README.
6. Optional – run the MCP server to let AI assistants manage translations:

   npm install @better-i18n/mcp   # or use npx when needed
   

   Follow the platform docs to connect Claude, Cursor, Windsurf, etc.

Key features of Better i18n

• GitHub‑native workflow – translations are created, reviewed, and merged as pull requests.
• CDN edge delivery – instant propagation of translation updates without redeploying the app.
• AI‑powered context‑aware translation using Google Gemini.
• Full TypeScript type safety across Next.js, React, Expo, and React Native.
• MCP server enables AI agents to read/write translation data programmatically.
• CLI scanner detects unused keys and helps keep translation files clean.
• ICU MessageFormat support for complex pluralisation and formatting.
• Open‑source SDKs under MIT license.

Use cases of Better i18n

• SaaS products that need rapid, zero‑downtime localization updates.
• Mobile apps built with Expo/React Native that require offline translation caching.
• Developer teams that want to keep localization work inside the same GitHub workflow as code reviews.
• AI‑augmented translation pipelines where agents can suggest or apply new translations via the MCP server.
• Multi‑region websites using Next.js where edge caching minimizes latency for end users.

FAQ from the Better i18n

Q: Do I need a dedicated server to run the MCP component? A: No. The MCP package can be started with a simple npx @better-i18n/mcp command (or installed globally) and configured with your API keys.

Q: Can I use Better i18n without the AI features? A: Yes. The SDKs work with manually supplied translation files; AI translation is optional and only invoked via the CLI or MCP when configured.

Q: How does CDN delivery work with my existing deployment? A: Translation JSON files are uploaded to Cloudflare’s edge network by the platform. Your app fetches them at runtime, so no redeployment is required for updates.

---

Why Better i18n?

Most localization tools weren't built for modern developer workflows. Better i18n is different:

• GitHub-native — translations sync as PRs, reviews happen in your existing workflow
• CDN-delivered — translations served from Cloudflare's edge network, updated without redeployment
• AI-powered — context-aware translation with Google Gemini, not word-by-word machine output
• TypeScript-first — full type safety across Next.js, React, Expo, and React Native
• MCP-ready — AI agents can manage translations through the Model Context Protocol

How it compares

Feature	Better i18n	Crowdin	Lokalise	Phrase
GitHub-first workflow	✅	Partial	Partial	❌
AI translation with context	✅	✅	✅	✅
CDN delivery (no redeploy)	✅	❌	❌	❌
TypeScript SDKs	✅	❌	❌	❌
MCP server for AI agents	✅	❌	❌	❌
CLI scanner (unused key detection)	✅	❌	❌	❌
ICU MessageFormat support	✅	✅	✅	✅
Open-source SDKs	✅	Partial	❌	❌
Free tier	✅	✅	❌	❌

Packages

Package	Description	Version
@better-i18n/cli	CLI for scanning, syncing, and managing translations
@better-i18n/next	Next.js SDK with middleware and hooks
@better-i18n/use-intl	React hooks for use-intl integration
@better-i18n/expo	Expo / React Native integration with offline caching
@better-i18n/core	Core utilities for locale handling and formatting
@better-i18n/mcp	MCP server for AI agent integration
@better-i18n/schemas	Shared Zod validation schemas

Quick Start

# Install the CLI
npm install -g @better-i18n/cli

# Initialize in your project
npx @better-i18n/cli init

# Scan your codebase for translation keys
npx @better-i18n/cli scan

# Sync translations with the Better i18n platform
npx @better-i18n/cli sync

Framework Integration

Next.js

npm install @better-i18n/next

// middleware.ts
import { createI18nMiddleware } from '@better-i18n/next';

export default createI18nMiddleware({
  locales: ['en', 'tr', 'de'],
  defaultLocale: 'en',
});

See the Next.js integration guide for routing, server components, and metadata setup.

React with use-intl

npm install @better-i18n/use-intl

import { BetterI18nProvider, useTranslations } from '@better-i18n/use-intl';

function App() {
  return (
    <BetterI18nProvider locale="en" messages={messages}>
      <MyComponent />
    </BetterI18nProvider>
  );
}

function MyComponent() {
  const t = useTranslations('common');
  return <h1>{t('welcome')}</h1>;
}

Expo / React Native

npm install @better-i18n/expo

import { BetterI18nExpoProvider, useTranslations } from '@better-i18n/expo';

export default function App() {
  return (
    <BetterI18nExpoProvider
      projectId="your-project-id"
      defaultLocale="en"
      fallbackMessages={fallback}
    >
      <HomeScreen />
    </BetterI18nExpoProvider>
  );
}

Supports offline caching, OTA translation updates, and automatic locale detection. See the Expo guide.

MCP Server (AI Agents)

npm install @better-i18n/mcp

Connect AI assistants like Claude, Cursor, or Windsurf to your translation workflow through the Model Context Protocol.

Agent Skill

Give your AI agent permanent better-i18n knowledge — SDK setup, key naming, CDN behavior, GitHub sync, and MCP tool usage — without pasting prompts each session.

npx skills add better-i18n/skills

Works with Claude Code, Cursor, Windsurf, and any agent that supports custom instructions. See github.com/better-i18n/skills.

Documentation

Visit docs.better-i18n.com for full documentation:

• Getting Started — setup and first project
• CLI Reference — all commands and options
• SDK Guides — Next.js, React, Expo integrations
• API Reference — REST API documentation
• MCP Integration — AI agent setup

Related

• better-i18n/skills — AI agent skills for i18n best practices
• better-i18n/status.better-i18n.com — open-source status page

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

License

MIT — Better i18n