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 #

Install the package #

bun add @better-i18n/server

Create the i18n singleton #

This instance is shared between Better Auth and your server middleware (Hono, Express, etc.) — one CDN cache for everything.

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

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

Add the provider to Better Auth #

import { betterAuth } from "better-auth";
import { createBetterAuthProvider } from "@better-i18n/server/providers/better-auth"; // [!code highlight]
import { i18n } from "./i18n";

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

That's it. The provider hooks into every Better Auth error response, detects the locale from the Accept-Language header, and translates the error message.

Add translations in the dashboard #

1. Go to your project in Better i18n
2. Create a namespace called auth
3. Add translation keys matching Better Auth error codes (e.g., INVALID_EMAIL_OR_PASSWORD)
4. Translate into your target languages
5. Publish — translations are live instantly

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", // [!code highlight]
  // 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 }) => { // [!code highlight]
    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 // [!code highlight]

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

app.use("*", betterI18n(i18n)); // Hono routes get c.get("t") // [!code highlight]

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

Related #

• Hono Middleware — Use the same i18n singleton with Hono for API response translations.
• Express & Node.js — Node.js adapter for Express, Fastify, and Koa.
• API Reference — Full reference for createServerI18n, Translator, and options.