---
title: "React API"
description: "Reference the React provider, hooks, messages, language controls, and diagnostics."
canonical_url: "https://docs.linguana.dev/docs/reference/react"
markdown_url: "https://docs.linguana.dev/docs/reference/react.md"
x_farming_labs_generated_preamble: true
---

# React API
URL: /docs/reference/react
LLM index: /llms.txt
Description: Reference the React provider, hooks, messages, language controls, and diagnostics.

# React API

## `LocaleProvider`

Required: `projectId`, `environment`, `initialLocale`, `fallbackLocale`, and `children`. Optional inputs include `publishableKey`, `catalogs`, `catalogEndpoint`, `cookieName`, `onDiagnostic`, `availableLocales`, `syncLocalePreference`, and `hydrationState`.

## `useTranslation()`

Returns:

- `locale`, `sourceLocale`, `ready`, and sampled `diagnostics`.
- async `setLocale(locale)`.
- `t(source, values?, options?)`.
- lower-level `translate(id, source, values?, components?)`.
- `availableLocales`.

It throws when called outside `LocaleProvider`.

## Explicit components

`<T>` accepts `id?`, required `defaultMessage`, `values?`, `components?`, and `context?`. `MessageComponents` maps tag names to React elements or chunk functions.

## Locale controls

`useLocaleOptions(query?)` returns filtered, display-name-sorted options with locale, readiness, and setter. `LanguageSelector` supplies a searchable input and accessible select.

## Catalog and preference helpers

- `loadCatalog(input)` fetches, parses, verifies integrity, and checks scope.
- `persistLocalePreference(locale, cookieName?, target?)` writes the first-party locale cookie.
- `createHydrationState(locale, catalogs)` validates and serializes initial state.
- `resolveLocale(input)` implements override, user preference, cookie, browser language, and default precedence.

## Diagnostics

`DiagnosticEvent.code` is `missing-translation`, `invalid-translation`, or `catalog-load-failed`, with locale, message, and optional message ID.

## See also

[Show translated content](/docs/build-with-code/show-translated-content) · [Integration testing](/docs/automate/test-integration)

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).