{t('title')}
{t('description')}
{t("title")}
{t("description")}
{languages.map((lang) => (
))}
)
}
```
### Why useLocaleRouter?
Unlike `useLocale().setLocale()`, `useLocaleRouter().navigate()`:
- ✅ Triggers proper SPA navigation
- ✅ Re-executes loaders (fresh messages)
- ✅ Updates URL correctly
- ✅ Works with browser history
```tsx
// ❌ State-only change (loaders don't re-run)
const { setLocale } = useLocale()
setLocale('tr')
// ✅ Router navigation (loaders re-run)
const { navigate } = useLocaleRouter()
navigate('tr')
```
## Generating Locale Paths
Use `localePath` to generate localized links:
```tsx
import { useLocaleRouter } from "@better-i18n/use-intl"
import { Link } from "@tanstack/react-router"
function Navigation() {
const { localePath } = useLocaleRouter()
return (
)
}
```
### Cross-Locale Links
Link to a specific locale:
```tsx
function Footer() {
const { localePath } = useLocaleRouter()
return (
)
}
```
## SEO Considerations
### Alternate Links
Add `hreflang` tags for search engines:
```tsx title="app/routes/__root.tsx"
export const Route = createRootRouteWithContext<{ locale: string }>()({
head: ({ loaderData }) => {
const { locale } = loaderData
const locales = ["en", "tr", "de"]
const baseUrl = "https://example.com"
const path = location.pathname.replace(`/${locale}`, "")
return {
links: [
// Canonical
{ rel: "canonical", href: `${baseUrl}${location.pathname}` },
// Alternates
...locales.map((loc) => ({
rel: "alternate",
hreflang: loc,
href: loc === "en" ? `${baseUrl}${path}` : `${baseUrl}/${loc}${path}`,
})),
// x-default
{ rel: "alternate", hreflang: "x-default", href: `${baseUrl}${path}` },
],
}
},
})
```
### Sitemap
Generate a sitemap with all locale variants:
```ts title="scripts/generate-sitemap.ts"
const locales = ["en", "tr", "de"]
const pages = ["/", "/about", "/contact", "/pricing"]
const urls = pages.flatMap((page) =>
locales.map((locale) => ({
url: locale === "en" ? page : `/${locale}${page}`,
alternates: locales.map((alt) => ({
hreflang: alt,
href: alt === "en" ? page : `/${alt}${page}`,
})),
}))
)
```
## Default Locale Handling
For the default locale (English), you may want to handle both:
- `/about` (no prefix)
- `/en/about` (with prefix)
```tsx title="app/routes/en/index.tsx"
import { createFileRoute, redirect } from "@tanstack/react-router"
// Redirect /en to /
export const Route = createFileRoute("/en/")({
beforeLoad: () => {
throw redirect({ to: "/" })
},
})
```
## Related
- [useLocaleRouter](/frameworks/locale) - Hook reference
- [Middleware](/frameworks/tanstack-start/middleware) - Locale detection
- [URL Strategy](/core/how-it-works) - Default locale patterns
---
# Middleware
Source: https://help.better-i18n.com/hi/docs/frameworks/tanstack-start/middleware
Configure automatic locale detection using TanStack Start middleware.
## Basic Setup
Create a middleware using the built-in helper:
```ts title="app/middleware/i18n.ts"
import { createBetterI18nMiddleware } from "@better-i18n/use-intl/middleware" // [!code highlight]
import { i18nConfig } from "../i18n.config"
export const i18nMiddleware = createBetterI18nMiddleware({ // [!code highlight]
projectId: i18nConfig.projectId, // [!code highlight]
defaultLocale: i18nConfig.defaultLocale, // [!code highlight]
}) // [!code highlight]
```
## Register Middleware
Add the middleware to your TanStack Start configuration:
```ts title="app/ssr.ts"
import { createStart } from "@tanstack/react-start/server"
import { i18nMiddleware } from "./middleware/i18n" // [!code ++]
export default createStart({
middleware: [i18nMiddleware], // [!code ++]
})
```
## Configuration Options
```ts
export const i18nMiddleware = createBetterI18nMiddleware({
// Required
projectId: "org/project",
defaultLocale: "en",
// Optional detection settings
detection: {
// Use Accept-Language header
browserLanguage: true,
// Use locale cookie
cookie: true,
// Cookie name (default: "locale")
cookieName: "locale",
// Cookie max age in seconds (default: 1 year)
cookieMaxAge: 60 * 60 * 24 * 365,
},
})
```
## Detection Order
The middleware detects locale in this order:
1. **URL Path** - `/tr/about` → `tr`
2. **Cookie** - `locale=tr` → `tr`
3. **Accept-Language Header** - `tr-TR,tr;q=0.9` → `tr`
4. **Default** - Falls back to `defaultLocale`
## How It Works
```
Request: GET /about
Headers: Accept-Language: tr-TR,tr;q=0.9,en;q=0.8
1. Check URL path → No locale prefix
2. Check cookie → No cookie
3. Check Accept-Language → "tr" detected
4. Set context.locale = "tr"
5. Set-Cookie: locale=tr
```
## Cookie Persistence
The middleware sets a cookie to persist the user's preference:
```ts
// First visit (Accept-Language: tr)
// → Cookie set: locale=tr; path=/; max-age=31536000
// Second visit (cookie exists)
// → Locale from cookie, no header check
```
## Disable Cookie
To disable cookie-based persistence:
```ts
export const i18nMiddleware = createBetterI18nMiddleware({
projectId: "org/project",
defaultLocale: "en",
detection: {
cookie: false,
browserLanguage: true,
},
})
```
## Disable Browser Detection
To ignore Accept-Language header:
```ts
export const i18nMiddleware = createBetterI18nMiddleware({
projectId: "org/project",
defaultLocale: "en",
detection: {
cookie: true,
browserLanguage: false,
},
})
```
## Custom Middleware
For advanced use cases, use `detectLocale` from `@better-i18n/use-intl/server` to handle locale detection:
```ts title="app/middleware/i18n.ts"
import { createMiddleware, getRequest } from "@tanstack/react-start/server"
import { detectLocale } from "@better-i18n/use-intl/server" // [!code highlight]
export const i18nMiddleware = createMiddleware().server(async ({ next }) => {
const request = getRequest()
const locale = detectLocale({ // [!code highlight]
request, // [!code highlight]
availableLocales: ["en", "tr", "de"], // [!code highlight]
defaultLocale: "en", // [!code highlight]
}) // [!code highlight]
return next({ context: { locale } })
})
```
`detectLocale` handles Accept-Language header parsing, quality factor (q-value) sorting, and best-match selection — no boilerplate needed.
### detectLocale Parameters
| Parameter | Description |
|---|---|
| `request` | Server `Request` object — `Accept-Language` header is read from here |
| `availableLocales` | List of supported locales to match against |
| `defaultLocale` | Fallback locale when no match is found |
> [!NOTE]
> Server-side, `request` is used to read the `Accept-Language` header. On client-side navigation, `navigator.languages` is used automatically — the same `detectLocale` function works in both environments.
### Advanced: Manual Parsing
For custom logic, you can use the lower-level utilities directly:
```ts
import { parseAcceptLanguage, matchLocale } from "@better-i18n/use-intl/server"
const languages = parseAcceptLanguage(request.headers.get("accept-language") ?? "")
// → [{ locale: "tr", quality: 1 }, { locale: "en", quality: 0.8 }]
const locale = matchLocale(languages, ["en", "tr", "de"], "en")
// → "tr"
```
## Accessing Locale in Routes
The middleware sets `context.locale` which is accessible in all routes:
```tsx title="app/routes/__root.tsx"
export const Route = createRootRouteWithContext<{ locale: string }>()({
loader: async ({ context }) => {
console.log("Detected locale:", context.locale)
const messages = await getMessages({
projectId: "org/project",
locale: context.locale,
})
return { messages, locale: context.locale }
},
})
```
## Debugging
Enable logging to debug locale detection:
```ts
export const i18nMiddleware = createMiddleware().server(async ({ next, request }) => {
const pathLocale = new URL(request.url).pathname.split("/")[1]
const cookieLocale = getCookie(request, "locale")
const browserLocale = request.headers.get("accept-language")
console.log("Locale detection:", {
path: pathLocale,
cookie: cookieLocale,
browser: browserLocale,
url: request.url,
})
// ... rest of middleware
})
```
## Common Issues
### Locale Not Persisting
**Symptom:** User's language preference resets on each visit.
**Solution:** Ensure cookie is set correctly:
```ts
detection: {
cookie: true,
cookieMaxAge: 60 * 60 * 24 * 365, // 1 year
}
```
### Wrong Locale Detected
**Symptom:** Browser in Turkish but app shows English.
**Solution:** Check detection order and cookie:
```ts
// Debug by logging
console.log({
cookie: request.headers.get("cookie"),
acceptLanguage: request.headers.get("accept-language"),
})
```
## Related
- [Setup](/frameworks/tanstack-start/setup) - Basic configuration
- [Routing](/frameworks/tanstack-start/routing) - Path-based locales
- [SSR](/frameworks/tanstack-start/ssr) - Server rendering
---
# TypeScript
Source: https://help.better-i18n.com/hi/docs/frameworks/tanstack-start/typescript
Enable autocomplete and type safety for your translation keys in TanStack Start applications.
## Setup
### Step 1: Create Type Declaration
Create a type declaration file that references your translation messages:
```ts title="app/types/i18n.d.ts"
import messages from '../locales/en.json'
type Messages = typeof messages // [!code highlight]
declare global { // [!code highlight]
interface IntlMessages extends Messages {} // [!code highlight]
} // [!code highlight]
```
> [!NOTE]
> The `IntlMessages` interface is used by `use-intl` to provide type safety for translation keys.
### Step 2: Add Local Translation File
For TypeScript to infer types, you need a local copy of your translations:
```json title="app/locales/en.json"
{
"home": {
"title": "Welcome to our app",
"description": "Get started by editing app/routes/index.tsx"
},
"greeting": {
"hello": "Hello, {name}!"
}
}
```
> [!WARNING]
> This file is only for type inference. At runtime, translations are still fetched from the Better i18n CDN.
## Usage
Once configured, you'll get autocomplete for translation keys:
```tsx
import { useTranslations } from '@better-i18n/use-intl'
function HomePage() {
const t = useTranslations('home')
return (
{/* ✅ TypeScript knows 'title' exists */}
)
}
```
## TanStack Start-Specific Types
### RouterContext and getMessages
The `getMessages` return type should match your `RouterContext` to ensure type safety across
the SSR boundary:
```ts title="app/router.tsx"
import type { Messages } from '@better-i18n/use-intl'
interface RouterContext {
locale: string
messages?: Messages
}
```
```tsx title="app/routes/__root.tsx"
import type { Messages } from '@better-i18n/use-intl'
// Loader return type is inferred automatically
export const Route = createRootRouteWithContext{t('title')}
{/* ❌ TypeScript error: 'invalid' doesn't exist */}{t('invalid')}
{t('title')}
} ``` ## Guide - [Setup](/frameworks/vite/setup) — Installation, provider configuration, and loading states. - [React Router](/frameworks/vite/react-router) — URL-based locale routing with React Router. - [TypeScript](/frameworks/vite/typescript) — Type-safe translation keys and autocomplete. ## 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. - [MCP Server](/mcp/getting-started) — Translate keys, check coverage, and publish — all from your editor via Cursor, Claude Code, or Windsurf. - [Agent Skill](/mcp/agent-skill) — Permanent better-i18n knowledge for your AI agent — SDK patterns, CDN behavior, key conventions. No prompts needed each session. --- # Setup Source: https://help.better-i18n.com/hi/docs/frameworks/vite/setup This guide walks you through installing Better i18n and setting up the provider in your Vite + React application. ## Installation ```bash tab="npm" npm install @better-i18n/use-intl @better-i18n/vite use-intl ``` ```bash tab="yarn" yarn add @better-i18n/use-intl @better-i18n/vite use-intl ``` ```bash tab="pnpm" pnpm add @better-i18n/use-intl @better-i18n/vite use-intl ``` ```bash tab="bun" bun add @better-i18n/use-intl @better-i18n/vite use-intl ``` ## Configuration ### Step 1: Add the Vite Plugin Configure `@better-i18n/vite` in your Vite config. This is the **single source of truth** for your project — no need to repeat it in the provider. ```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({ projectId: 'your-org/your-project' }), // [!code ++] react(), ], }) ``` The plugin fetches translations **server-side** (in the Vite dev server or at build time) and injects them into your HTML as a ` ``` Or via `window.betterContent.track(...)` after `init()`. ## Property validation Properties must be primitive: `string`, `number`, `boolean`, or `null`. Nested objects and arrays are rejected: - **Development** (`NODE_ENV !== 'production'`): throws `Error("Invalid property...")` - **Production**: silently strips the invalid property and warns in debug mode This catches bugs early without breaking your app in prod. ```ts // ✅ OK track('content.view', { entryId: 'abc', count: 1, featured: true }) // ❌ Throws in dev, stripped in prod track('content.view', { entryId: 'abc', author: { id: '1' } }) ``` ## Why is my API key safe? | Concern | Mitigation | |---|---| | Key extracted from JS bundle | Key is write-only — can't read content or analytics | | Spam events from stolen key | Server-side rate limit (per IP, per project) + CF WAF | | Cross-project access | Key scoped to a single `projectId` at validation time | | Sensitive PII in properties | You control payload — never log emails, only IDs | Phase 1 mitigations: KV-cached key validation (1h TTL), CF Workers CPU/memory limits, server-side validation rejects malformed payloads. ## Proxy to avoid ad blockers Ad blockers may block requests to `content.better-i18n.com`. Proxy the track endpoint through your own domain so the browser only sees first-party requests. **Next.js rewrites** The simplest option for Next.js apps. Add a rewrite rule in `next.config.js`: ```js title="next.config.js" /** @type {import('next').NextConfig} */ const nextConfig = { async rewrites() { return [ { source: '/api/ca/:path*', destination: 'https://content.better-i18n.com/:path*', }, ] }, } export default nextConfig ``` Then point the SDK to your proxy: ```tsxHello
` | | `jsx-attribute` | Hardcoded attributes | `{t('title')}
; // Detected as: hero.title ``` ### Server Components (Async Functions) ```tsx // ✅ Direct string namespace const t = await getTranslations('welcome'); return{t('title')}
; // Detected as: welcome.title // ✅ Object with namespace property const t = await getTranslations({ locale: params.locale, namespace: 'maintenance' }); return{t('message')}
; // Detected as: maintenance.message // ⚠️ Root scoped (no namespace) const t = await getTranslations(); return{t('global.title')}
; // Detected as: global.title (root scope) ``` ### Supported Patterns - **`useTranslations('namespace')`** - Client component with namespace - **`getTranslations('namespace')`** - Server component with namespace - **`getTranslations({ locale, namespace: 'namespace' })`** - Server with locale - **`useTranslations()` / `getTranslations()`** - Root scoped (no namespace prefix) - **Standard Methods**: All patterns support `t()`, `t.raw()`, `t.rich()`, and `t.has()`. ### Dynamic Namespaces If a namespace is a variable or template literal (e.g., ``useTranslations(`pages.${slug}`)``), it is reported as **unknown-scoped** in `--verbose` mode and skipped from metrics to prevent false positives. --- ## Flattening rules To ensure CLI metrics match the Better i18n UI: 1. **Primitives are leaves**: Strings, numbers, and booleans are counted as keys. 2. **Arrays are leaves**: `meta.keywords: ["i18n", "cli"]` is counted as **one key**, not two. This matches the UI's "Base Key" counting. 3. **Objects are containers**: Keys like `pages.home.hero` representing a grouping of sub-keys are ignored in the final key count. --- ## JSON Output Use `--format json` for CI scripts and automation. ```json { "project": { "workspace": "my-org", "slug": "my-app", "sourceLocale": "en" }, "localKeys": { "total": 1223 }, "comparison": { "missingInRemote": { "pages.bestApps": ["pages.bestApps.meta.title"] }, "unusedInCode": { "old": ["old.unused_key"] }, "missingCount": 473, "unusedCount": 386 }, "coverage": { "local": 59, "remote": 63 }, "files": 246, "duration": 850 } ``` --- ## CI Integration ### Fail build on missing keys ```bash # Using jq to check missingCount better-i18n sync --format json | jq -e '.comparison.missingCount == 0' > /dev/null || exit 1 ``` ### List missing keys in CI logs ```bash better-i18n sync --format json | jq '.comparison.missingInRemote' ``` --- # doctor Source: https://help.better-i18n.com/hi/docs/cli/doctor Run a full i18n health check on your project in one command. `doctor` combines five analysis layers — code scanning, coverage, quality, performance, and CDN sync — and produces a single health score with actionable diagnostics. ## When to use `doctor` - **Before opening a PR**: Catch missing translations, hardcoded strings, and placeholder mismatches before review. - **In CI pipelines**: Block merges when the health score drops below the pass threshold. - **Orphan key audits**: Identify translation keys that are no longer used in code. - **Deployment checks**: Verify that local keys are in sync with the remote CDN before shipping. - **First health baseline**: Run once on an existing project to understand its i18n debt. --- ## Usage ```bash better-i18n doctor # Full analysis of current directory better-i18n doctor --dir ./src # Scan a specific directory better-i18n doctor --format json # JSON output for machine consumption better-i18n doctor --ci # Exit code 1 if score below threshold better-i18n doctor --report # Upload report to Better i18n dashboard better-i18n doctor --report --api-key $KEY # Upload with explicit API key better-i18n doctor --skip-sync # Skip CDN comparison better-i18n doctor --skip-code # Skip hardcoded string detection better-i18n doctor --skip-health # Skip translation file analysis better-i18n doctor --verbose # Detailed per-file diagnostic output ``` ## Options | Option | Description | |--------|-------------| | `-d, --dir