next-intl setup guide

Turn your next-intl JSON into a team workflow

Run npx @i18nexus/cli init to import your existing next-intl messages, manage translations in i18nexus, and keep your Next.js app synced automatically.

$npx @i18nexus/cli init
Account and project setup
Existing next-intl JSON import
Dashboard workflow for your team
MCP setup for AI coding agents
next-intl AI workflow

Shared Localization for Teams using next-intl

Keep next-intl message files generated and synced while your team and AI agents manage strings through i18nexus.

Editing Translation JSON Directly

Shared Localization Workflow

One command setup

Run init in your Next.js project

Run the command in your next-intl project and follow the prompts. The CLI signs you in, creates the i18nexus project, imports your existing messages, and finishes the recommended local setup.

npx @i18nexus/cli init

What init gives you

Creates your i18nexus project

Init creates an i18nexus project for this Next.js app. If you do not have an account yet, the authentication flow lets you sign up; if you do, just sign in.

Detects your next-intl message files

Init reads your local next-intl JSON, detects languages and message structure, and imports your existing translations into i18nexus.

Sets up local sync

Init adds scripts for pulling translations before builds and listening for updates from dashboard edits, teammate changes, and MCP updates.

Configures the MCP

Add project-scoped MCP config and agent instructions for Claude, Codex, or both, so AI agents manage strings through i18nexus instead of editing local JSON.

What you get when it finishes...

Your next-intl messages are now organized in i18nexus, with AI translation that uses your app context. Your team edits, reviews, verifies, and tracks copy from one dashboard. Edits made in i18nexus sync live to local development environments, and production builds pull the latest translations automatically....and that's it. Your app still uses next-intl, and your developer workflow does not change at all, except now you do not have to manage translation JSON files.

Local sync

How does i18nexus sync next-intl messages?

Init installs @i18nexus/cli as a dev dependency and updates your package.json so local next-intl JSON stays current during development and every build starts with the latest translations.

"scripts": {
  "dev": "concurrently -p none \"next dev\" \"i18nexus listen\"",
  "prebuild": "i18nexus pull",
  "build": "next build",
  "start": "next start",
  "lint": "next lint"
}

During development

i18nexus listen runs next to your Next.js dev server. When strings are added, edited, or deleted from the dashboard or through the MCP, your local next-intl message files refresh automatically.

During builds

i18nexus pull downloads the latest generated translation files. Init adds it as prebuild, so npm runs it automatically before npm run build.

Keep the source of truth clear

Do not maintain source copy by editing local next-intl JSON. Use the dashboard or MCP to change source strings in i18nexus, then sync the generated output your app needs.

Team workflow

Use the dashboard and MCP together

These workflows are complementary. Both write to i18nexus, which stays the source of truth for your next-intl source strings and translations.

Use the dashboard for team editing and review

The dashboard is the shared workspace for next-intl source strings, languages, descriptions, and translation review.

  • Edit copy without opening translation JSON files.
  • Review AI-generated translations before they ship.
  • Add descriptions so translators and AI understand where text appears.
  • Invite teammates who should manage copy without working in a code editor.

Use the MCP while AI agents edit code

The MCP gives AI coding agents a structured way to create, search, and update i18nexus strings while they work in your Next.js app.

  • Agents add user-facing text to i18nexus instead of editing local next-intl JSON.
  • String descriptions include page, component, and UI context.
  • Project-scoped config keeps the agent pointed at the right i18nexus project.
  • Token scopes let you decide whether agents add, update, move, or delete strings.
Read the MCP guide

Related references

Level up your localization

It only takes a few minutes to streamline your translations forever.

Get started