Quick Start

Installation

npm install @better-i18n/use-intl use-intl

yarn add @better-i18n/use-intl use-intl

pnpm add @better-i18n/use-intl use-intl

bun add @better-i18n/use-intl use-intl

Add the Provider

Wrap your app with BetterI18nProvider:

src/App.tsx

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

function App() {
  return (
    <BetterI18nProvider
      project="your-org/your-project"  // From dashboard
      locale="en"
    > // [!code ++]
      <YourApp />
    </BetterI18nProvider> 
  )
}

The project value uses org/project format from your Better i18n dashboard.

Use Translations

Use the useTranslations hook in any component:

src/components/Welcome.tsx

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

export function Welcome() {
  const t = useTranslations('home') 

  return (
    <div>
      <h1>{t('title')}</h1>
      <p>{t('description')}</p>
    </div>
  )
}

That's It!

Your app now:

✅ Fetches translations from the Better i18n CDN
✅ Supports dynamic language switching
✅ Auto-discovers available languages from your project

Choose Your Framework

Each guide covers framework-specific patterns like SSR, routing, and middleware.

TanStack Start

Full-stack React with SSR support, path-based routing, and middleware.

Vite + React

Client-side React applications with Vite bundler.

Next.js

Deep integration with Next.js App Router via @better-i18n/next.

Remix / Hydrogen

CDN-powered i18n for Remix and Shopify Hydrogen with loader-based translations.

Expo / React Native

iOS and Android with offline caching, device locale detection, and Expo Router integration.

Framework Comparison

Framework	Rendering	Routing	Best For
TanStack Start	SSR + CSR	File-based	Full-stack React, SEO
Vite + React	CSR	Optional	SPAs, prototypes, landing pages
Next.js	SSR + CSR	App Router	Production apps
Remix	SSR	Loader-based	E-commerce (Hydrogen), full-stack

Feature Matrix

Feature	TanStack Start	Vite	Next.js	Remix
Server messages	✅	✅ (plugin)	✅	✅
Path-based locale	✅	✅ (plugin)	✅	✅
Middleware	✅	✅ (plugin)	✅	❌
Static generation	❌	❌	✅	❌
Edge runtime	✅	❌	✅	✅
Bundle size	~2KB	~2KB	~5KB	~2KB

Not sure? Start with Vite + React for the simplest setup, then upgrade to TanStack Start or Next.js when you need SSR.

AI Tooling

Let your AI agent manage translations and understand better-i18n conventions automatically.

MCP Server

Connect Cursor, Claude Code, or Windsurf to your project — translate keys, check coverage, and publish directly from your editor.

Agent Skill

Give your AI agent permanent better-i18n knowledge — SDK patterns, CDN behavior, and key conventions. No prompts needed each session.

# MCP server — tool execution
npx -y @better-i18n/mcp@latest

# Agent skill — persistent knowledge
npx skills add better-i18n/skills

Core Concepts

Learn the fundamentals that apply to all frameworks:

How It Works

CDN architecture, caching, and URL strategy.

Provider

Configure the BetterI18nProvider for your app.

Translations

useTranslations hook, namespaces, and interpolation.

Locale Management

useLocale, useLanguages, and LanguageSwitcher.

Formatting

Format dates, numbers, and lists with useFormatter.

Server Utilities

Pre-load messages for SSR and server-side translation.