Next.js i18n with @babelize/sdk/next

@babelize/sdk/next provides Next.js-specific integration: a proxy for locale detection, server component translation, and build-time lockfile generation.

npm install @babelize/sdk @babelize/next

	`npx babelize translate` (CLI)	`@babelize/sdk` (this page)
Your code	Rewritten once: hardcoded text becomes next-intl `t()` calls	You wrap text in `babelizeRSC()` / `babelize()` yourself
Translations live in	JSON locale files you commit and can edit	A lockfile the build plugin generates
URLs	A URL per language (`/ja/…`) by default	One URL; the locale comes from a cookie or the browser
Best for	An existing app you want translated with the least work	New code where you want translation calls written by hand

The proxy detects the user's locale and makes it available to your server and client components. In Next.js 16 the file is proxy.ts (it was middleware.ts before; that name still works but is deprecated).

// proxy.ts (middleware.ts before Next.js 16)
import { babelizeMiddleware } from "@babelize/sdk/next";

export default babelizeMiddleware({
  supportedLocales: ["en", "ja", "fr", "de"],
  defaultLocale: "en",
});

export const config = {
  matcher: "/:path*",
};

Detection Order

The proxy determines the locale by checking these sources in order:

babelize-locale cookie — persists the user's preference across visits
Accept-Language HTTP header — the browser or system language
defaultLocale — the configured fallback

It sets the x-babelize-locale response header and babelize-locale cookie so both server and client components can access the current locale.

Options

interface BabelizeMiddlewareOptions {
  supportedLocales?: string[];  // Restrict to specific locales
  defaultLocale?: string;       // Fallback locale (default: "en")
  localeCookie?: string;        // Cookie name (default: "babelize-locale")
}

Server Components

Use babelizeRSC() in async Server Components. It reads the locale from the proxy's x-babelize-locale header and translations from the pre-loaded lockfile.

Load the lockfile once at module scope, then use babelizeRSC anywhere:

// app/page.tsx
import { babelizeRSC, loadLockfile } from "@babelize/sdk/next";
import lockfile from "../babelize-lock.json";

loadLockfile(lockfile);

export default async function Home() {
  return (
    <div>
      <h1>{await babelizeRSC("Welcome to Babelize")}</h1>
      <p>{await babelizeRSC("Hello {name}", { name: "World" })}</p>
    </div>
  );
}

Server component translations come entirely from the lockfile — no API calls, no JavaScript shipped to the client.

Client Components

For interactive parts of your app, use the React hooks from @babelize/sdk/react:

"use client";

import { useBabelize, useLocale } from "@babelize/sdk/react";

export function LocaleAwareSection() {
  const babelize = useBabelize();
  const { setLocale } = useLocale();

  return (
    <div>
      <p>{babelize("This text updates when locale changes")}</p>
      <button onClick={() => setLocale("fr")}>
        {babelize("Switch to French")}
      </button>
    </div>
  );
}

Build Plugin

Add the build plugin to automatically discover and pre-translate strings during next build:

// next.config.ts
import withBabelize from "@babelize/next";

export default withBabelize(
  {
    // your Next.js config
  },
  {
    locales: ["ja", "fr", "de"],
  },
);

The plugin scans your source files, extracts strings, and generates babelize-lock.json — no manual configuration needed.

Architecture

Request → Edge Middleware → Server Component → Client Component
             │                    │                    │
         Detects locale       Reads lockfile       React hooks
         Sets cookie          Returns string       Re-renders
         Sets header           No API calls        Cache-aware

TypeScript

import type { BabelizeMiddlewareOptions } from "@babelize/sdk/next";

interface BabelizeMiddlewareOptions {
  supportedLocales?: string[];
  defaultLocale?: string;
  localeCookie?: string;
}

Next.js

SDK or CLI?

Proxy

Detection Order

Options

Server Components

Client Components

Build Plugin

Architecture

TypeScript

Further Reading

next-intl vs react-i18next

Implement i18n in Next.js with next-intl

On this page