i18next JSON v4

React & i18next Translation

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

TransLocale documentation · Updated September 17, 2026 · Markdown quick start

New to TransLocale? Follow the screenshot walkthrough to create a project, add keys and translations, review wording, and get credentials. Use this guide’s message format and catalog names for your app. Your project ID is under Project settings → Credentials.

1. Install

Run this from your application directory.

npm install @translocale/i18next i18next

2. Connect your project

Create a cloud project and replace PROJECT_UUID with its ID. The source and target languages must match your local configuration. Adjust the example locales to your project.

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

Approve translation access in the browser:

npx translocale-i18next login --scope translate

Sign-in is shared with your other TransLocale tools for this project. Keep credentials in developer tooling or CI. Your deployed app reads its own translation files.

3. Wire up your app

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.

4. Translate, review, and download

Inspect the plan before running translate. The example caps the job at 1,000 source characters across its target languages. Waiting stops after two minutes; a timeout leaves the job running.

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

Replace JOB_UUID with the completed job ID. Before pulling revision 1, save that revision in the dashboard and review its wording. Choose the exact saved revision you want to ship, then repeat pull for each target locale. Revision 0 is the original generated output.

Normal application builds use saved catalogs and make no paid translation requests.

Already have translations?

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.

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

{
  "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

{
  "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

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

i18next plural rules and the count option

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

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

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

Compare combined source and target documents

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.

Current limits

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.

The service accepts up to 100 KB and 200 messages per source document. Expanded target messages must also fit the adapter's limits. Read the file compatibility guide.

Check a file before connecting

Try the free source file checker to inspect message structure without an account. For assistant setup and read-only catalog checks, follow the MCP localization guide.