# Getting Started

Client-side i18n setup for Vite and React applications

## Overview

Better i18n for Vite works in two modes:

- **With `@better-i18n/vite` plugin (recommended)** — Translations are fetched server-side and injected into HTML before React mounts. Zero FOUC, no client-side CDN requests, SEO-friendly.
- **Without plugin (CSR fallback)** — Translations are fetched on the client after mount. Quick to set up, but shows a brief loading state on first render.

<Callout type="tip">
  Use the `@better-i18n/vite` plugin for production apps. It works like Next.js SSR — translations are embedded in the HTML, so the first render always has real content.
</Callout>

<Callout type="tip">
  **Integrating with AI?** Run `npx skills add better-i18n/skills` first — your agent (Cursor, Claude Code, or Windsurf) will already know the SDK patterns, CDN behavior, and key conventions. Then just ask it to set up the integration for you. [Learn more →](/mcp/agent-skill)
</Callout>

## Features

<Cards>
  <Card title="Zero Config" icon="Sparkles">
    Point to your project and go - translations load automatically from the CDN.
  </Card>
  <Card title="React Suspense" icon="Pause">
    Native Suspense support for elegant loading states.
  </Card>
  <Card title="Type Safety" icon="Shield">
    Full TypeScript support with autocomplete for translation keys.
  </Card>
  <Card title="Locale Storage" icon="Database">
    Built-in localStorage persistence for user locale preference.
  </Card>
</Cards>

## Quick Start

### With Vite Plugin (Recommended)

```bash
bun add @better-i18n/use-intl @better-i18n/vite use-intl
```

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { betterI18n } from '@better-i18n/vite' // [!code ++]

export default defineConfig({
  plugins: [
    betterI18n({ project: 'your-org/your-project' }), // [!code ++]
    react(),
  ],
})
```

```tsx title="src/App.tsx"
import { BetterI18nProvider, LocaleDropdown } from '@better-i18n/use-intl' // [!code ++]

function App() {
  return (
    <BetterI18nProvider> // [!code ++]
      <LocaleDropdown />
      <YourApp />
    </BetterI18nProvider> // [!code ++]
  )
}
```

No `project`, `locale`, or `messages` props needed — the plugin handles everything.

### Without Plugin (CSR)

```tsx title="src/App.tsx"
import { BetterI18nProvider } from '@better-i18n/use-intl' // [!code ++]

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

```tsx title="src/components/Hello.tsx"
import { useTranslations } from '@better-i18n/use-intl' // [!code highlight]

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

  return <h1>{t('title')}</h1>
}
```

## Guide

<Cards>
  <Card title="Setup" icon="Settings" href="/frameworks/vite/setup">
    Installation, provider configuration, and loading states.
  </Card>
  <Card title="React Router" icon="Route" href="/frameworks/vite/react-router">
    URL-based locale routing with React Router.
  </Card>
  <Card title="TypeScript" icon="FileCode" href="/frameworks/vite/typescript">
    Type-safe translation keys and autocomplete.
  </Card>
</Cards>

## Comparison

| Feature | Vite | Vite + Plugin | TanStack Start | Next.js |
|---------|------|---------------|----------------|---------|
| Rendering | CSR | SSR injection | CSR + SSR | CSR + SSR |
| FOUC | Yes | **No** | No | No |
| URL routing | Optional | Optional | Built-in | Built-in |
| SEO | Limited | **Embedded** | Full | Full |
| Client CDN requests | Yes | **No** (initial) | No | No |

The `@better-i18n/vite` plugin brings SSR-like benefits to Vite apps without requiring a full SSR setup.


## AI Tooling

Now that you've integrated the SDK, your AI agent can check coverage, translate keys, and publish — all without leaving your editor.

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