How to Localize Better Auth: Error Messages, UI, and Emails (Complete Guide)

import { betterAuth } from "better-auth";
import { i18n } from "@better-auth/i18n";

export const auth = betterAuth({
  plugins: [
    i18n({
      defaultLocale: "en",
      translations: {
        tr: {
          INVALID_EMAIL_OR_PASSWORD: "Geçersiz e-posta veya şifre",
          USER_NOT_FOUND: "Kullanıcı bulunamadı",
          EMAIL_NOT_VERIFIED: "E-posta doğrulanmadı",
          // ... 45 more keys
        },
        de: {
          INVALID_EMAIL_OR_PASSWORD: "Ungültige E-Mail oder Passwort",
          // ... all keys again
        },
      },
      detection: ["cookie", "header"],
      localeCookie: "locale",
    }),
  ],
});

npm install @better-i18n/server

// src/i18n.ts
import { createServerI18n } from "@better-i18n/server";

export const i18n = createServerI18n({
  project: "your-org/your-project",
  defaultLocale: "en",
});

// src/auth.ts
import { betterAuth } from "better-auth";
import { createBetterAuthProvider } from "@better-i18n/server/providers/better-auth";
import { i18n } from "./i18n";

export const auth = betterAuth({
  plugins: [
    createBetterAuthProvider(i18n, {
      localeCookie: "locale", // reads user's chosen language from cookie
    }),
  ],
});

// src/App.tsx
import { BetterI18nProvider } from "@better-i18n/use-intl";

function App() {
  return (
    <BetterI18nProvider
      project="your-org/your-project"
      localeCookie  // writes "locale" cookie on every language change
    >
      <YourApp />
    </BetterI18nProvider>
  );
}

User picks Turkish → cookie "locale=tr" written
  → Next auth request includes cookie
  → Server reads cookie → fetches Turkish translations from CDN
  → Error message returned in Turkish

import { DEFAULT_AUTH_KEYS } from "@better-i18n/server/providers/better-auth";

// DEFAULT_AUTH_KEYS contains all 48 error codes with English defaults
console.log(Object.keys(DEFAULT_AUTH_KEYS).length); // 48

// src/lib/auth-client.ts
import { createAuthClient } from "better-auth/react";
import { getLocaleCookie } from "@better-i18n/core";

export const authClient = createAuthClient({
  baseURL: "/api/auth",
  fetchOptions: {
    headers: {
      // Getter reads fresh cookie value on every request
      get "Accept-Language"() {
        return getLocaleCookie("locale") ?? "en";
      },
    },
  },
});

// src/auth.ts
import { createServerI18n } from "@better-i18n/server";

const i18n = createServerI18n({
  project: "your-org/your-project",
  defaultLocale: "en",
});

export const auth = betterAuth({
  emailAndPassword: {
    sendResetPassword: async ({ user, url }, request) => {
      // Detect locale from request cookie or Accept-Language
      const locale = request
        ? await i18n.detectLocaleFromHeaders(request.headers)
        : "en";

      // Get translations for email namespace
      const t = await i18n.getTranslator(locale, "emails");

      await sendEmail({
        to: user.email,
        subject: t("reset_password_subject"),
        html: `
          <h1>${t("reset_password_title")}</h1>
          <p>${t("reset_password_body")}</p>
          <a href="${url}">${t("reset_password_button")}</a>
        `,
      });
    },
  },
  emailVerification: {
    sendVerificationEmail: async ({ user, url }, request) => {
      const locale = request
        ? await i18n.detectLocaleFromHeaders(request.headers)
        : "en";
      const t = await i18n.getTranslator(locale, "emails");

      await sendEmail({
        to: user.email,
        subject: t("verify_email_subject"),
        html: `
          <h1>${t("verify_email_title")}</h1>
          <p>${t("verify_email_body")}</p>
          <a href="${url}">${t("verify_email_button")}</a>
        `,
      });
    },
  },
  plugins: [
    createBetterAuthProvider(i18n, { localeCookie: "locale" }),
  ],
});

// middleware.ts — detect locale and set cookie
import { betterI18nMiddleware } from "@better-i18n/next/middleware";

export default betterI18nMiddleware({
  project: "your-org/your-project",
  defaultLocale: "en",
  locales: ["en", "tr", "de", "fr"],
});

<BetterI18nProvider
  project="your-org/your-project"
  localeCookie="locale"
>
  <App />
</BetterI18nProvider>

import { betterI18n } from "@better-i18n/server/hono";
import { i18n } from "./i18n";

app.use("*", betterI18n(i18n));
// c.get("locale") and c.get("t") available in all routes