Next.js

Get started with Better i18n in your Next.js app. Our SDK integrates seamlessly with next-intl to provide a type-safe, CDN-powered translation experience.

Install the SDK #

Install the package via your preferred package manager:

npm install @better-i18n/next

Configure i18n #

Create an i18n.config.ts file in your project root. This file is shared between the SDK and the Better i18n CLI.

import { createI18n } from "@better-i18n/next";

export const i18n = createI18n({
  projectId: "my-company/web-app",
  defaultLocale: "en",
});

Set Up next-intl #

Configure the next-intl request handler using the exported configuration.

import { i18n } from "../i18n.config";

export default i18n.requestConfig;

Add Middleware #

Register the i18n middleware in your middleware.ts.

import { i18n } from "./i18n.config";

// Simple usage
export default i18n.betterMiddleware();

export const config = {
  matcher: ["/((?!api|_next|.*\\..*).*)"],
};

For apps with authentication, use the callback pattern:

import { i18n } from "./i18n.config";
import { NextResponse } from "next/server";

export default i18n.betterMiddleware(async (request, { locale, response }) => {
  const isLoggedIn = !!request.cookies.get("session")?.value;

  if (!isLoggedIn && request.nextUrl.pathname.includes("/dashboard")) {
    return NextResponse.redirect(new URL(`/${locale}/login`, request.url));
  }
});

export const config = {
  matcher: ["/((?!api|_next|.*\\..*).*)"],
};

Use Translations #

Now you can use standard next-intl hooks. The CLI will automatically track these scopes for syncing.

import { useTranslations } from "next-intl";

export default function Home() {
  const t = useTranslations("common");

  return <h1>{t("welcome")}</h1>;
}

Next Steps #

• Configure caching and revalidation
• Set up middleware options
• Explore the API reference

AI Tooling #

Now that you've integrated the SDK, your AI agent can check coverage, translate keys, and publish — all without leaving your editor.

• MCP Server — Translate keys, check coverage, and publish — all from your editor via Cursor, Claude Code, or Windsurf.
• Agent Skill — Permanent better-i18n knowledge for your AI agent — SDK patterns, CDN behavior, key conventions. No prompts needed each session.