Quick Start

Installation #

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

Add the Provider #

Wrap your app with BetterI18nProvider:

import { BetterI18nProvider } from '@better-i18n/use-intl' // [!code ++]

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

Use Translations #

Use the useTranslations hook in any component:

import { useTranslations } from '@better-i18n/use-intl' // [!code highlight]

export function Welcome() {
  const t = useTranslations('home') // [!code highlight]

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

That's It! #

Your app now:

• Supported: Fetches translations from the Better i18n CDN
• Supported: Supports dynamic language switching
• Supported: 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 #

Feature Matrix #

---

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.