Getting Started
Set up @better-i18n/next in 5 minutes
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.
Prerequisite: Before starting, create a project at dash.better-i18n.com. Your project identifier will be in the format org/project (e.g., my-company/web-app).
Integrating with AI? Run npx skills add better-i18n/skills first — your agent (Cursor, Claude Code, or Windsurf) will already know the SDK patterns, CDN behavior, and key conventions. Then just ask it to set up the integration for you. Learn more →
Install the SDK
Install the package via your preferred package manager:
npm install @better-i18n/nextyarn add @better-i18n/nextpnpm add @better-i18n/nextbun add @better-i18n/nextConfigure 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({
project: "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.