Better Auth Localization Plugin

A localization plugin for Better Auth that automatically translates error messages from the core library and official plugins. ezgif-6723e2cdfd4aa9

Features

🌍 Multi-language support - Built-in translations with easy custom locale addition
🔄 Automatic translation - Seamlessly translates error messages without changing your application logic
🎯 Type-safe - Full TypeScript support with autocomplete for custom translations
🛡️ Fallback system - Fallback to default messages when translations are missing
🔧 Flexible locale detection - Support for custom locale resolution from headers, cookies, or databases
⚡ Zero runtime overhead - Translations are bundled at build time

Installation

npm install better-auth-localization
# or
yarn add better-auth-localization
# or
pnpm add better-auth-localization

Quick Start

Basic Usage with Built-in Locale

import { betterAuth } from "better-auth";
import { localization } from "better-auth-localization";

export const auth = betterAuth({
  // ... your config
  plugins: [
    localization({
      defaultLocale: "pt-BR", // Use built-in Portuguese translations
      fallbackLocale: "default" // Fallback to English
    })
  ]
});

Dynamic Locale Detection

localization({
  defaultLocale: "pt-BR",
  fallbackLocale: "default",
  getLocale: async (request) => {
    try {
      // Use your existing locale detection logic
      // This could come from cookies, database, JWT tokens, etc.
      const userLocale = await getUserLocale(request);
      
      return userLocale || 'default';
    } catch (error) {
      console.warn('Error detecting locale:', error);
      return 'default'; // Safe fallback
    }
  }
})

// Example getUserLocale implementation (adapt to your needs)
async function getUserLocale(request: Request): Promise<string | null> {
  // Could check user preferences from database, cookies, headers, etc.
  // return await db.user.getLocale(userId);
  // return getCookieValue(request, 'locale');
  // return request.headers.get('x-user-locale');
}

Custom Translations

localization({
  defaultLocale: "fr",
  fallbackLocale: "pt-BR", // Can also use built-in locales as fallback
  translations: {
    "fr": {
      USER_NOT_FOUND: "Utilisateur non trouvé",
      INVALID_PASSWORD: "Mot de passe invalide",
      INVALID_EMAIL: "Email invalide",
      SESSION_EXPIRED: "Session expirée"
    },
    "es": {
      USER_NOT_FOUND: "Usuario no encontrado",
      INVALID_PASSWORD: "Contraseña inválida",
      INVALID_EMAIL: "Email inválido",
      SESSION_EXPIRED: "Sesión expirada"
    }
  },
});

Overriding Built-in Translations

localization({
  defaultLocale: "pt-BR",
  translations: {
    "pt-BR": {
      // Override specific messages
      USER_NOT_FOUND: "Usuário não foi encontrado no sistema",
      INVALID_PASSWORD: "A senha fornecida está incorreta"
    }
  }
});

Language Support Status

Currently supported languages:

🇧🇷 Portuguese (pt-BR) - ✅ Complete
🇵🇹 Portuguese (pt-PT) - ✅ Complete
🇪🇸 Spanish (es-ES) - ✅ Complete
🇫🇷 French (fr-FR) - ✅ Complete
🇵🇱 Polish (pl-PL) - ✅ Complete (Thanks @stripsior)
🇮🇩 Indonesian (id-ID) - ✅ Complete (Thanks @finly)
🇯🇵 Japanese (ja-JP) - ✅ Complete (Thanks @HRTK92)
🇸🇦 Arabic (ar-SA) - ✅ Complete (Thanks @mosaleh-dev)
🇬🇷 Greek (el-GR) - ✅ Complete (Thanks @DomVournias)
🇸🇪 Swedish (sv-SE) - ✅ Complete (Thanks @yamanadamnor)
🇮🇹 Italian (it-IT) - ✅ Complete (Thanks @mattiamalonni)
🇩🇪 German (de-DE) - ✅ Complete (Thanks @NiklasDah)
- 🇩🇪 German (informal, "du") (de-DE-informal) (default)
- 🇩🇪 German (formal, "Sie") (de-DE-formal)
🇨🇳 Traditional Chinese (zh-Hant) - ✅ Complete (Thanks @MarkLee425)
🇨🇳 Simplified Chinese (zh-Hans) - ✅ Complete (Thanks @MarkLee425)
🇰🇷 Korean (ko-KR) - ✅ Complete (Thanks @MarkLee425)
🇮🇳 Hindi (hi-HI) - ✅ Complete (Thanks @MarkLee425)
🇹🇷 Turkish (tr-TR) - ✅ Complete (Thanks @furkanczay)
🇳🇱 Dutch (nl-NL) - ✅ Complete (Thanks @InvixGG)
- 🇳🇱 Dutch (informal, "je") (nl-NL-informal) (default)
- 🇳🇱 Dutch (formal, "u") (nl-NL-formal)
🇮🇷 Persian/Farsi (fa-IR) - ✅ Complete (Thanks @Yasser5711)
🇷🇺 Russian (ru-RU) - ✅ Complete (Thanks @draneone)
🇮🇳 Marathi (mr-MR) - ✅ Complete (Thanks @OutOfBoundCats)
🇩🇰 Danish (da-DK) - ✅ Complete (Thanks @BjornFrancke)
🇷🇴 Romanian (ro-RO) - ✅ Complete (Thanks @danielavornic)
🇮🇶 Kurdish Sorani (ckb-IQ) - ✅ Complete (Thanks @didar-dev)

Built-in Translations

The plugin comes with built-in translations for all Better Auth error codes, including:

Core Library:

User-related errors (USER_NOT_FOUND, USER_ALREADY_EXISTS, etc.)
Session errors (SESSION_EXPIRED, FAILED_TO_CREATE_SESSION, etc.)
Authentication errors (INVALID_PASSWORD, INVALID_EMAIL, etc.)
Password validation (PASSWORD_TOO_SHORT, PASSWORD_TOO_LONG)
Social authentication errors
Account management errors

Official Plugins:

Admin plugin error messages
Anonymous authentication plugin
API Key plugin
Device authorization plugin
Email OTP plugin
Generic OAuth plugin
Have I Been Pwned plugin
Multi-session plugin
Organization plugin
Passkey plugin
Phone number plugin
Two-factor authentication plugin
Username plugin

For a complete and specific list, refer to the Better Auth documentation.

Contributing

We welcome and appreciate contributions! Help us expand language support by adding new translations.

Adding a new language (no merge conflicts)

This repo auto-generates the translations index to avoid PR conflicts when multiple languages are added in parallel.

Run the locale creation script:

npm run generate:locale
# or
pnpm generate:locale
# or
yarn generate:locale

Input your desired locale (e.g., nl_NL, fr_CA, es_MX)
The script will automatically:
- Create the main translation file with the correct structure
- Generate plugin-specific translation files with proper types
- Update all necessary LOCALES objects
- Use the correct error code types for each plugin
Translate the generated content to match your locale
Do not edit or commit src/translations/index.ts.
Submit your pull request. The index is generated automatically by the build and tests.

The build runs the generator automatically to ensure the index stays up to date.

JSPM