# React & i18next localization with TransLocale

Keep namespace files, interpolation, and language-specific plural forms in your existing i18next workflow.

Canonical page: https://translocale.io/integrations/i18next

## Install

@translocale/i18next 0.2.9. Node.js 22.16+. Message format: Native i18next JSON v4.

```bash
npm install @translocale/i18next i18next
```

## Connect and configure

Create a cloud project under Projects → New project. Copy PROJECT_UUID from Project settings → Credentials, and match the project languages to your catalogs. Browser login stores authoring access outside the app. For CI, create a credential under Project settings → Credentials and put it in the TRANSLOCALE_TOKEN secret. App delivery uses a separate read-only credential under Releases → App delivery.

```bash
npx translocale-i18next init --api https://translocale.io --project PROJECT_UUID --source en --locales en,fr,ar --namespaces common,checkout
```

```bash
npx translocale-i18next login --scope translate
```

Setup creates src/translocale-resources.ts with imports of local namespace files. Use those resources when initializing i18next, and use react-i18next in components. Download every configured target before building. Create a separate i18next instance for each server request.

## Translate and review

Inspect the plan before translating. The translate example starts a job capped at 1,000 source characters across target languages. Replace JOB_UUID with its returned ID. Save and review revision 1 before pulling it, or choose the exact revision you want to ship. Repeat pull for each target language. Normal builds do not start translation jobs.

```bash
npx translocale-i18next plan
npx translocale-i18next translate --max-characters 1000 --wait
npx translocale-i18next pull --job JOB_UUID --locale fr --revision 1
npx translocale-i18next check
```

Run npx translocale-i18next discover --source en to inspect locale and namespace directories. Initialize from a reviewed candidate using the included discovery guide. Sync can merge a newer cloud revision with local edits across namespace files, with explicit choices for conflicts.

## Project setup and credentials

The screenshot walkthrough covers project creation, catalog import, keys, review, releases, and credentials. Use this framework’s message format and catalog identities. Authoring tokens belong in developer tools and CI; app delivery credentials only read published wording. Flutter’s flutter-connect writes DELIVERY_* build settings, while the dashboard download uses projectId, channel, schemaHash, deliveryToken, and apiBaseUrl.

- [Follow the illustrated first-project guide](https://translocale.io/docs/getting-started)

## i18next pluralization: suffix keys and count

For React apps using react-i18next, write JSON v4 plural keys such as items_one and items_other. Call t('items', {count: 2}) with a numeric count. The runtime chooses the suffix for the active language; count is required for that selection.

locales/en/checkout.json:

```json
{
  "items_one": "{{count}} item",
  "items_other": "{{count}} items"
}
```

Plural categories depend on the language. English uses one and other. Arabic uses zero, one, two, few, many, and other, so copying the English key set leaves the Arabic catalog incomplete. Keep the count placeholder in each translated branch.

locales/ar/checkout.json:

```json
{
  "items_zero": "لا توجد عناصر ({{count}})",
  "items_one": "عنصر واحد ({{count}})",
  "items_two": "عنصران ({{count}})",
  "items_few": "{{count}} عناصر",
  "items_many": "{{count}} عنصرًا",
  "items_other": "{{count}} عنصر"
}
```

After the runtime setup above, use the checkout namespace in a React component. With English active, a count of 2 renders “2 items”. Switching the active locale to Arabic selects its corresponding branch.

Inside a component using react-i18next:

```text
const {t} = useTranslation("checkout");
return <p>{t("items", {count: 2})}</p>;
```

- [i18next plural rules and the count option](https://www.i18next.com/translation-function/plurals)

## Check missing plural forms before building

For the example files, configure sourceLocale as en, locales as [en, ar], and include checkout in namespaces. Each local namespace file contains its messages directly. The package combines namespace files into a document with namespace roots when talking to TransLocale.

Check all configured local catalogs:

```bash
npx translocale-i18next check
```

The check reports a missing Arabic items_two branch or a changed placeholder such as {{total}} in place of {{count}}. Restore the branch or placeholder, then run the check again. This validates catalog structure; a reviewer still needs to assess the translated wording.

To check the same example through the generic CLI, save each combined document with checkout at the root, then supply both locale flags. Wrap the Arabic messages the same way in ar.json.

en.json for the generic CLI:

```json
{
  "checkout": {
    "items_one": "{{count}} item",
    "items_other": "{{count}} items"
  }
}
```

Compare combined source and target documents:

```bash
npx translocale check --source en.json --target ar.json --format i18next --source-locale en --target-locale ar
```

These checks do not start translation jobs. The browser checker inspects one source file; use the CLI comparison when you already have a target catalog.

- [Check a source file in the browser](https://translocale.io/app)
- [Choose a JSON translation format](https://translocale.io/docs#json-translation-examples)

## Compatibility and further setup

Default separators and JSON v4 plural suffixes are required. Legacy formats, dynamic nesting options, and custom separators are not supported.

The React browser consumer and local Cloudflare server rendering have been tested. React Native device behavior remains pending.

- [Complete framework guide, including runtime examples](https://translocale.io/integrations/i18next)
- [MCP guide](https://translocale.io/docs/mcp)
- [Free source file checker](https://translocale.io/app)