Getting Started

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).

Install the SDK

Install the package via your preferred package manager:

npm install @better-i18n/next

yarn add @better-i18n/next

pnpm add @better-i18n/next

bun add @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.

i18n.config.ts

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.

src/i18n/request.ts

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

export default i18n.requestConfig;

Add Middleware

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:

middleware.ts

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.

app/page.tsx

import { useTranslations } from "next-intl"; 

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

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

Install the SDK

Configure i18n

Set Up next-intl

Add Middleware

Use Translations

Next Steps

On this page