Migration

Your message files come with you unchanged. Almost all of the work is in three files, and this page maps every API you are likely to be using.

It assumes you know what a node is — that page is the one that makes the rest click.

Should you migrate?

Established i18n libraries are good at what they do — be honest about the trade. They are battle-tested at a scale Intl-T is not yet, their ecosystems are larger (more docs, more answered questions, first-class Crowdin / Tolgee / Lokalise workflows), and those built on intl-messageformat are strictly ICU-compliant, quoting rules included. Two things some of them ship that Intl-T does not have:

• Localized pathnames (/en/about ↔ /es/acerca-de). There is no Intl-T equivalent.
• A dedicated formatter API surface (useFormatter-style hooks with now/timezone state).

If you depend on either, or on a translation-management pipeline built around your current library, staying put is a reasonable call.

What you get by switching:

• Your JSON is the API. t.HomePage.welcome({ user }) — autocomplete at every depth, and the variables of that message inferred from that message. No key registry, no global.d.ts augmentation, no codegen step.
• Routing is decoupled from translation. createTranslation and createNavigation know nothing about each other. Adopt the tree without the router, or run the router with no [locale] segment at all.
• Zero third-party runtime dependencies, and no plugin in next.config.ts.
• One API everywhere. App Router, Pages Router, a Vite SPA and plain Node all use the same tree.
• Another locale is just another branch: t.es.HomePage.title, without switching the app's locale.

API map

Everything below assumes i18n/translation.ts and i18n/navigation.ts from Quick Start.

Translating

Providing

Routing

File by file

1. i18n/request.ts → i18n/translation.ts

getRequestConfig disappears. There is no per-request message loading to configure: you import the tree once, and it is the same tree on the server and on the client.

import { createTranslation } from "intl-t/next";
import en from "./messages/en.json";
import es from "./messages/es.json";

export const { Translation, useTranslation, getTranslation, t } = createTranslation({
  locales: { en, es },
});

To load locales on demand instead, pass loaders — see Dynamic Import.

2. i18n/routing.ts + i18n/navigation.ts → i18n/navigation.ts

One config produces the proxy, the navigation helpers and generateStaticParams.

import { defineRouting } from "next-intl/routing";

export const routing = defineRouting({
  locales: ["en", "es"],
  defaultLocale: "en",
  localePrefix: "as-needed",
});

import { createNavigation } from "next-intl/navigation";
import { routing } from "./routing";

export const { Link, redirect, usePathname, useRouter } = createNavigation(routing);

import { createNavigation } from "intl-t/next";

export const { proxy, Link, redirect, usePathname, useRouter, useLocale, generateStaticParams } = createNavigation({
  allowedLocales: ["en", "es"] as const,
  defaultLocale: "en",
  pathPrefix: "default", // = localePrefix: "as-needed"
});

3. middleware.ts → proxy.ts

createNavigation returns the same function under both names, so on Next ≤ 15 only the file name and the export differ.

export { proxy } from "@/i18n/navigation";

export const config = {
  matcher: "/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)",
};

export { middleware as default } from "@/i18n/navigation";

export const config = {
  matcher: "/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)",
};

Chaining your own logic works the same way — withProxy (or withMiddleware) hands you the response Intl-T already built:

import { withProxy } from "@/i18n/navigation";

export const proxy = withProxy(async (req, ev, response) => {
  // `response` already carries the resolved locale (headers + cookie)
  return response;
});

export const config = {
  matcher: "/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)",
};

4. The layout

NextIntlClientProvider becomes <Translation>, and there is nothing to pass it but the locale.

import { NextIntlClientProvider } from "next-intl";
import { getMessages, setRequestLocale } from "next-intl/server";

export default async function RootLayout({ children, params }) {
  const { locale } = await params;
  setRequestLocale(locale);
  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>{children}</NextIntlClientProvider>
      </body>
    </html>
  );
}

import { Translation } from "@/i18n/translation";
import { setRequestLocale } from "intl-t/next";

export { generateStaticParams } from "@/i18n/navigation";

export default async function RootLayout({ children, params }: { children: React.ReactNode; params: Promise<{ locale: string }> }) {
  const { locale } = await params;
  await setRequestLocale(locale);

  return (
    <html lang={locale}>
      <body>
        <Translation locale={locale}>{children}</Translation>
      </body>
    </html>
  );
}

5. The components

import { getTranslation } from "@/i18n/translation";

export default async function Page() {
  const t = await getTranslation("HomePage");

  return (
    <>
      <h1>{t.title}</h1>
      <p>{t.welcome({ user: "Ada" })}</p>
    </>
  );
}

"use client";

import { useTranslation } from "@/i18n/translation";

export function Hero() {
  const t = useTranslation("HomePage");

  return (
    <>
      <h1>{t.title}</h1>
      <p>{t.welcome({ user: "Ada" })}</p>
    </>
  );
}

The namespace argument is the same string you passed to useTranslations. What comes back is the node at that path, so t("title") still works — but t.title is the form that is typed and autocompleted.

Message files

They carry over unchanged. Nesting becomes the tree, and ICU is supported: plural, select, selectordinal, number, date all render as they did.

{
  "HomePage": {
    "title": "Hello world!",
    "welcome": "Welcome, {user}!",
    "followers": "{count, plural, =0 {No followers yet} =1 {One follower} other {# followers}}",
    "invited": "{gender, select, female {She} male {He} other {They}} invited you",
    "price": "{amount, number, currency}",
  },
}

One thing must be checked before you ship: reserved keys.

This script lists every collision in a message file before you start:

import { invalidKeys } from "intl-t";
import en from "../i18n/messages/en.json";

const reserved = new Set<string>([...invalidKeys, "en", "es"]); // + your locale codes

(function walk(node: unknown, path: string[] = []) {
  if (typeof node !== "object" || node === null) return;
  for (const [key, value] of Object.entries(node)) {
    if (reserved.has(key)) console.log("reserved:", [...path, key].join("."));
    walk(value, [...path, key]);
  }
})(en);

Two smaller differences, both rare in practice:

• ICU quoting is not implemented. "Escaped '{name}' braces" injects name and keeps the quotes, where strict ICU would print a literal {name}. If you use '…' to escape braces, rewrite those messages.
• A missing key renders its own path. t("does.not.exist") renders "does.not.exist" rather than throwing — handy for spotting a key you renamed and forgot.

Rich text

t.rich() does not exist. It does not need to: tags written in a message are rendered as React elements by the normal call, and a variable whose name matches a tag replaces that tag with your component.

// "terms": "Please accept the <link>terms</link>."
t.rich("terms", {
  link: chunks => <Link href="/terms">{chunks}</Link>,
});

// "terms": "Please accept the <link>terms</link>."   ← same message
t("terms", {
  link: ({ children }) => <Link href="/terms">{children}</Link>,
});

The handler is a component, not a chunks callback: it receives props, so the children arrive as children. In exchange, tags you do not map render as themselves:

So every b, i, strong and em mapping in your next-intl call sites can simply be deleted. Only tags that must become a component (a Link, a tooltip) still need an entry.

See React § component injection for nesting and attributes.

i18next

The tree model is close to i18next's, so most of a migration is mechanical.

• {{double braces}} work. "Hi {{name}}" and "Hi {name}" both inject name. Interpolation needs no rewrite.
• useTranslation("ns") keeps its name — and const { t } = useTranslation("ns") still destructures, because t is the node itself. Namespaces become top-level keys of one JSON file per locale.
• Flat dotted keys need one line of config. { "nav.home": "Home" } is a key literally containing a dot, and t("nav.home") splits on ., so it resolves nothing. Either nest the keys (recommended — that is what gives you the typed tree), or keep them flat and change the separator:

export const { t, useTranslation } = createTranslation({
  locales: { en, es },
  pathSeparator: "/", // now t("nav.home") is one key, not a path
});

• Suffix plurals must become ICU. i18next selects item_one / item_other from count; Intl-T does not. Rewrite them:

- "item_one": "{{count}} item",
- "item_other": "{{count}} items"
+ "item": "{count, plural, one {# item} other {# items}}"

react-intl

• Messages move from defineMessages into the same JSON files, keyed by nesting instead of by flat id. If your ids are dotted (home.title), the note above applies: nest them, or set pathSeparator.
• intl.formatMessage({ id: "home.title" }, values) → t.home.title(values).
• <FormattedMessage id="home.title" /> → {t.home.title}, or the <Translation> component.
• ICU carries over as-is. <FormattedNumber> / <FormattedDate> become {amount, number, currency} / {date, date, long} inside the message.

Gotchas

Variables stick to the node

Passing variables writes them into the node, so that children inherit them and chained calls work. On the client that is what you want. On a long-lived server, two concurrent requests share one tree and can overwrite each other:

const node = t("greet", { user: "Alice" }); // request A
await db.query(…); //  request B runs t("greet", { user: "Bob" })
String(node); //  "Hello Bob!"  ← A renders B's data

Give each request its own instance — it costs a few microseconds and nothing else changes:

import { t } from "@/i18n/translation";
import { TranslationNode } from "intl-t";

export default async function Page() {
  const rt = new TranslationNode({ settings: t.settings }); // isolated per request
  const user = await getUser();

  return <p>{rt.HomePage.welcome({ user: user.name })}</p>;
}

Rendering to strings and sending those to the client is unaffected — by then the text is already a string. The same applies to any message where a missing variable would be filled in by whatever a previous request left there.

useLocale comes from navigation, not from createTranslation

createTranslation does expose a useLocale name, but it is an alias of the translation hook — not locale state. Take the real one from createNavigation (Next.js) or from intl-t/react (SPA, Pages Router). It returns both shapes:

"use client";
import { useLocale } from "@/i18n/navigation";

export function LocaleSwitcher() {
  const [locale, setLocale] = useLocale(); // or: const { locale, setLocale } = useLocale()
  return <button onClick={() => setLocale("es")}>{locale}</button>;
}

proxy.ts, not middleware.ts

Next.js 16 renamed the file. createNavigation returns proxy and middleware as the same function, so on Next ≤ 15 you keep middleware.ts and export middleware as default. Do not forget the matcher — it is not inherited from createNavigation.

Pick the entry point by router, not by framework

intl-t/next pulls in App Router server modules (RSC, server actions). Importing it from Pages Router page code fails to compile.

createNavigation is the exception: it always comes from intl-t/next, and on the Pages Router you may only import it from proxy.ts — never from a page. The Pages Router example shows the full split.

Next steps