Next.js Plugin

@babelize/next discovers strings and generates the lockfile when next build or next dev starts. It works with Turbopack (Next 16's default bundler) and webpack.

Setup

Wrap your Next.js configuration with withBabelize:

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

const nextConfig = {
  // your existing Next.js config
};

export default withBabelize(nextConfig, {
  locales: ["ja", "fr", "de"],
});

Set your API key in .env.local:

BABELIZE_API_KEY=bblz_sk_xxxxxxxxx

Run your build:

npm run build

pnpm build

yarn build

bun run build

The plugin scans your source files, translates discovered strings, and writes babelize-lock.json.

How It Works

withBabelize returns a Next.js config function. When Next loads it for next build or next dev, before any bundler starts, the plugin:

1. Scans all source files matching the include patterns for babelize(), babelize.p() and babelizeRSC() calls
2. Translates each unique string via the Babelize API for every configured locale
3. Writes the lockfile to your project root

Because the lockfile is written before bundling, every build imports that build's translations, and import lockfile from "../babelize-lock.json" resolves on a fresh clone. In next dev it runs once at startup: restart dev to pick up new strings.

A locale that fails to translate fails the build, so a partial lockfile never ships. With no API key, the plugin warns and writes the lockfile without translations.

withBabelize also accepts a config function, so it composes with other wrappers: withBabelize(withMDX(nextConfig), options).

Options

interface BabelizeNextPluginOptions {
  apiKey?: string;                // API key (default: BABELIZE_API_KEY env)
  locales?: string[];             // Target locales
  output?: string;                 // Lockfile path (default: "babelize-lock.json")
  functionName?: string;           // Function name to scan (default: "babelize")
  apiUrl?: string;                 // API endpoint
  include?: string[];              // Source glob patterns
}

Default include patterns:

[
  "src/**/*.{tsx,ts,jsx,js}",
  "app/**/*.{tsx,ts,jsx,js}",
  "pages/**/*.{tsx,ts,jsx,js}",
]

Integration with @babelize/sdk/next

After the lockfile is generated, load it in your app using @babelize/sdk/next:

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

loadLockfile(lockfile);

export default async function Home() {
  const welcome = await babelizeRSC("Welcome to Babelize");
  return <h1>{welcome}</h1>;
}

And set up the middleware for locale detection:

// middleware.ts
import { babelizeMiddleware } from "@babelize/sdk/next";

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

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