Better Auth

@better-i18n/server/providers/better-auth creates a Better Auth plugin that automatically translates error messages (like "Invalid email or password") into your users' language — fetched from the CDN at runtime.

Setup

bun add @better-i18n/server

npm install @better-i18n/server

pnpm add @better-i18n/server

yarn add @better-i18n/server

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

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

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

export const auth = betterAuth({
  // ...your config
  plugins: [
    createBetterAuthProvider(i18n), 
    // ...other plugins
  ],
});

How It Works

When Better Auth returns an error (e.g., invalid login), the provider:

1. Detects if the response is an APIError with a body.code (e.g., INVALID_EMAIL_OR_PASSWORD)
2. Resolves the user's locale from the Accept-Language header
3. Fetches translations from the CDN — all namespaces are served in a single translations.json per locale, and the provider scopes to the auth namespace automatically
4. Replaces body.message with the translated string

If a translation is missing, the original English message is preserved and a warning is logged — auth never breaks because of a missing translation.

Client (Accept-Language: tr) → Better Auth → APIError
  → Provider: detectLocale("tr")
  → CDN: /{org}/{project}/tr/translations.json → { "auth": { "INVALID_EMAIL_OR_PASSWORD": "..." } }
  → Response: { "code": "INVALID_EMAIL_OR_PASSWORD", "message": "Geçersiz e-posta veya şifre" }

Locale Detection

By default, the provider reads the Accept-Language header. For most apps, you'll want cookie-based detection instead — it uses the locale the user actually chose in your app, not their browser/OS language.

Cookie-based (recommended)

Pair with the provider's localeCookie prop — same cookie name on both sides:

createBetterAuthProvider(i18n, {
  localeCookie: "locale", 
  // reads the "locale" cookie from the request
  // falls back to Accept-Language if cookie is missing
})

// Client writes the cookie automatically:
<BetterI18nProvider localeCookie> {/* default cookie name: "locale" */}
  <App />
</BetterI18nProvider>

Custom callback

For advanced cases (database, user profile, custom header):

createBetterAuthProvider(i18n, {
  getLocale: async ({ headers }) => { 
    const userId = getUserIdFromSession(headers);
    return await db.users.getLocale(userId) ?? "en";
  },
})

Options

Default Error Codes

The provider exports DEFAULT_AUTH_KEYS — all Better Auth core error codes with English defaults. Create these keys in your project's auth namespace, then translate them from the dashboard.

Full Key Reference (48 keys)

You can also access these programmatically:

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

// 40+ keys with English defaults
Object.entries(DEFAULT_AUTH_KEYS).forEach(([key, message]) => {
  console.log(`${key}: ${message}`);
});

Sharing with Hono Middleware

The i18n singleton is designed to be shared. Use the same instance for both Better Auth and your Hono API:

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

const app = new Hono<{
  Variables: { locale: string; t: Translator };
}>();

app.use("*", betterI18n(i18n)); // Hono routes get c.get("t")

// Better Auth also uses the same i18n → shared CDN cache, zero extra fetches

Related