# Next.js localization with TransLocale

Translate nested messages, connect next-intl, and check catalogs before building your app.

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

## Install

@translocale/next 0.1.9. Node.js 22.16+. Message format: Nested ICU JSON.

```bash
npm install @translocale/next next-intl
```

## 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-next init --api https://translocale.io --project PROJECT_UUID --source en --locales en,fr,ar
```

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

Add the plugin to next.config.ts. It connects the generated request configuration and checks your catalogs. Set up locale routes and NextIntlClientProvider using the next-intl App Router guide. Download every configured target locale before building.

```text
import { createTransLocalePlugin } from "@translocale/next/plugin";
export default createTransLocalePlugin()({});
```

## 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-next plan
npx translocale-next translate --max-characters 1000 --wait
npx translocale-next pull --job JOB_UUID --locale fr --revision 1
npx translocale-next check
```

Run npx translocale-next discover --source en to find existing catalogs. The package README's discovery guide explains how to initialize from a reviewed candidate. For later updates, sync previews incoming wording against your local edits and a recorded cloud revision; apply only after reviewing its plan hash.

## 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)

## next-intl plurals in nested ICU JSON

With next-intl, keep plural branches inside an ICU message. The Cart object below is a namespace; items is one message with an exact zero case, a one branch, and the required other fallback. The # symbol inserts the count.

messages/en.json:

```json
{
  "Cart": {
    "greeting": "Hello, {name}",
    "items": "{count, plural, =0 {Your cart is empty} one {# item} other {# items}}"
  }
}
```

messages/fr.json:

```json
{
  "Cart": {
    "greeting": "Bonjour, {name}",
    "items": "{count, plural, =0 {Votre panier est vide} one {# article} other {# articles}}"
  }
}
```

After configuring next-intl's provider and message loading, call useTranslations('Cart') inside a synchronous component. Passing count: 2 renders “2 items” in English and “2 articles” in French. Passing count: 0 selects the explicit =0 message.

Inside a component using next-intl:

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

- [next-intl ICU plural syntax](https://next-intl.dev/docs/usage/translations#cardinal-pluralization)

## Validate ICU messages and target placeholders

Set sourceLocale to en and include en and fr in your TransLocale config. Keep both files in messages/{locale}.json, or set files to your catalog path pattern. Run the package check before building and after changing a catalog during development.

Check configured Next.js catalogs:

```bash
npx translocale-next check
```

Deleting Cart.greeting from the French file produces a missing-key error. Replacing {name} with {firstName} produces a placeholder mismatch. Removing other from the plural expression makes the ICU message invalid. Fix the reported message and repeat the check.

Compare two files with the generic CLI:

```bash
npx translocale check --source messages/en.json --target messages/fr.json --format icu-json
```

Choose Nested ICU JSON in the browser checker for these files. Use the CLI to compare a target catalog with its source. Validation does not start a paid translation job or judge the quality of the French wording.

- [Check a source ICU JSON file](https://translocale.io/app)
- [Compare supported JSON formats](https://translocale.io/docs#json-translation-examples)

## Compatibility and further setup

One JSON catalog per locale. Arrays, non-string leaves, and keys containing dots are rejected.

App Router with webpack has been tested. Turbopack, Pages Router examples, and automatic source-code extraction remain pending.

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