---
title: Quick Start
description: Get Better i18n running in your React app in under 5 minutes
icon: Rocket
---

## Installation

<Tabs items={["npm", "yarn", "pnpm", "bun"]}>
  <Tab value="npm">
  ```bash
  npm install @better-i18n/use-intl use-intl
  ```
  </Tab>
  <Tab value="yarn">
  ```bash
  yarn add @better-i18n/use-intl use-intl
  ```
  </Tab>
  <Tab value="pnpm">
  ```bash
  pnpm add @better-i18n/use-intl use-intl
  ```
  </Tab>
  <Tab value="bun">
  ```bash
  bun add @better-i18n/use-intl use-intl
  ```
  </Tab>
</Tabs>

## Add the Provider

Wrap your app with `BetterI18nProvider`:

```tsx title="src/App.tsx"
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 ++]
  )
}
```

<Callout type="info">
  The `project` value uses `org/project` format from your Better i18n dashboard.
</Callout>

## Use Translations

Use the `useTranslations` hook in any component:

```tsx title="src/components/Welcome.tsx"
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:
- ✅ 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.

<Cards>
  <Card title="TanStack Start" icon="Rocket" href="/frameworks/tanstack-start">
    Full-stack React with SSR support, path-based routing, and middleware.
  </Card>
  <Card title="Vite + React" icon="Zap" href="/frameworks/vite">
    Client-side React applications with Vite bundler.
  </Card>
  <Card title="Next.js" icon="Box" href="/frameworks/nextjs">
    Deep integration with Next.js App Router via `@better-i18n/next`.
  </Card>
  <Card title="Remix / Hydrogen" icon="Repeat" href="/frameworks/remix">
    CDN-powered i18n for Remix and Shopify Hydrogen with loader-based translations.
  </Card>
  <Card title="Expo / React Native" icon="Smartphone" href="/frameworks/expo">
    iOS and Android with offline caching, device locale detection, and Expo Router integration.
  </Card>
</Cards>

### 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 |

<Callout type="tip">
  **Not sure?** Start with [Vite + React](/frameworks/vite) for the simplest setup, then upgrade to TanStack Start or Next.js when you need SSR.
</Callout>

---

## AI Tooling

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

<Cards>
  <Card title="MCP Server" icon="Bot" href="/mcp/getting-started">
    Connect Cursor, Claude Code, or Windsurf to your project — translate keys, check coverage, and publish directly from your editor.
  </Card>
  <Card title="Agent Skill" icon="Sparkles" href="/mcp/agent-skill">
    Give your AI agent permanent better-i18n knowledge — SDK patterns, CDN behavior, and key conventions. No prompts needed each session.
  </Card>
</Cards>

```bash
# 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:

<Cards>
  <Card title="How It Works" icon="Globe" href="/core/how-it-works">
    CDN architecture, caching, and URL strategy.
  </Card>
  <Card title="Provider" icon="Box" href="/frameworks/provider">
    Configure the BetterI18nProvider for your app.
  </Card>
  <Card title="Translations" icon="Type" href="/frameworks/translations">
    useTranslations hook, namespaces, and interpolation.
  </Card>
  <Card title="Locale Management" icon="Globe" href="/frameworks/locale">
    useLocale, useLanguages, and LanguageSwitcher.
  </Card>
  <Card title="Formatting" icon="Calendar" href="/frameworks/formatting">
    Format dates, numbers, and lists with useFormatter.
  </Card>
  <Card title="Server Utilities" icon="Server" href="/frameworks/server">
    Pre-load messages for SSR and server-side translation.
  </Card>
</Cards>
