Next.js

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

Middleware

The middleware detects the user's locale and makes it available to your server and client components.

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

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

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

Detection Order

The middleware 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 middleware'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

On this page