Better Auth Localization Plugin

Common errors

• TypeError: betterAuth is not a function

  cause Attempting to use `betterAuth` as a default import instead of a named import.
  fix Change `import betterAuth from 'better-auth';` to `import { betterAuth } from 'better-auth';`

• Error: Peer dependency better-auth@^1.5.0 not met.

  cause Your installed `better-auth` version does not satisfy the `better-auth-localization` v3.x requirement.
  fix Upgrade your `better-auth` package to version `1.5.0` or higher using `npm install better-auth@latest` or `pnpm add better-auth@latest`.

• Error: USER_NOT_FOUND (or similar untranslated error message)

  cause Localization plugin is not configured or activated, or the requested locale is not found and no fallback is provided.
  fix Verify that `localization` is included in the `betterAuth` plugins array. Ensure `defaultLocale` and `fallbackLocale` are correctly set, or implement a `getLocale` function that returns a supported locale.

• Type 'Request' is not assignable to type 'Request'.

  cause Potential type mismatch for the `Request` object passed to `getLocale` when integrating with specific web frameworks or custom server setups.
  fix Ensure the `Request` object provided to `getLocale` matches the expected `Request` interface (e.g., from `@types/node` or a specific web framework's types). You may need to cast the request object or adjust your type definitions.

Warnings

• breaking Version 3.0.0 of `better-auth-localization` requires `better-auth` v1.5.0 or newer. Ensure your core `better-auth` dependency is updated to avoid compatibility issues.
  Fix: Update `better-auth` to `>=1.5.0` in your project's `package.json` and reinstall dependencies.
• gotcha The `getLocale` option for dynamic locale detection requires manual implementation. The plugin does not automatically infer locale from user sessions or requests; you must provide a function to extract it from `Request` headers, cookies, or other sources.
  Fix: Implement a `getLocale: async (req: Request) => Promise<string | null>` function within the `localization` plugin options to parse the locale from the incoming request (e.g., `req.headers.get('x-user-locale')` or from cookies/JWTs).
• gotcha Prior to v2.1.6, providing custom translations for a specific error code would completely override all other translations for that language. Since v2.1.6, custom translations are merged, allowing partial overrides while retaining built-in translations for unspecified error codes.
  Fix: If upgrading from an older version and relying on partial custom translations, ensure you are on `v2.1.6` or later. For older versions, you would need to provide a complete translation object for any language you wish to customize.
• gotcha The `localization` plugin must be included in the `plugins` array of your `betterAuth` configuration. Forgetting to register it will result in no localization being applied to error messages.
  Fix: Ensure `localization(...)` is added to the `plugins: [...]` array when initializing `betterAuth`.

Install

• npm install better-auth-localization npm
• yarn add better-auth-localization yarn
• pnpm add better-auth-localization pnpm

Imports

• localization
  wrong:

  const localization = require('better-auth-localization');

  correct:

  import { localization } from 'better-auth-localization';

  This package is designed for ESM environments, particularly when integrated with `better-auth`. Use named imports.
• LocalizationPluginOptions
  wrong:

  import { LocalizationPluginOptions } from 'better-auth-localization';

  correct:

  import type { LocalizationPluginOptions } from 'better-auth-localization';

  Use `import type` for type-only imports to ensure they are stripped during compilation, especially important in TypeScript projects.
• betterAuth
  wrong:

  import betterAuth from 'better-auth';

  correct:

  import { betterAuth } from 'better-auth';

  While not directly from `better-auth-localization`, `betterAuth` is essential for integrating the plugin. It is a named export from the core `better-auth` library.

Quickstart

Initializes `better-auth` with the `localization` plugin, setting a default locale and a fallback. This demonstrates basic integration.

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

// Example: Simulate a basic better-auth config
const exampleConfig = {
  secret: process.env.AUTH_SECRET ?? 'super-secret-development-key',
  cookie: {
    secure: process.env.NODE_ENV === 'production'
  }
};

export const auth = betterAuth({
  ...exampleConfig,
  plugins: [
    localization({
      defaultLocale: 'pt-BR', // Use built-in Portuguese translations
      fallbackLocale: 'default', // Fallback to English
      // For dynamic locale detection, you would add a getLocale function here:
      // getLocale: async (req) => {
      //   // Imagine reading locale from a cookie or header
      //   const cookieHeader = (req as any)?.headers?.get("cookie");
      //   const cookies = cookieHeader ? Object.fromEntries(cookieHeader.split('; ').map(c => c.split('='))) : {};
      //   return cookies.locale ?? 'default';
      // }
    })
  ]
});

// To demonstrate usage (this part is illustrative and not part of the quickstart plugin setup):
// try {
//   // Simulate an authentication call that might throw an error
//   // const user = await auth.signIn('test@example.com', 'wrong-password');
// } catch (error: any) {
//   console.log('Localized error:', error.message); // Should output translated message
// }