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" }

Custom Locale Detection

By default, the provider reads the Accept-Language header. Override this when locale is stored elsewhere:

createBetterAuthProvider(i18n, {
  getLocale: async ({ headers }) => { 
    // Read from cookie, database, user profile, etc.
    const cookie = headers?.get("cookie") ?? "";
    const match = cookie.match(/locale=([a-z]{2})/);
    return match?.[1] ?? "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

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