Registry / auth-security / better-auth-localization

better-auth-localization

library3.0.0jsnpmunverified

The `better-auth-localization` plugin provides comprehensive internationalization (i18n) capabilities for error messages generated by the `better-auth` library and its official plugins. It aims to offer a seamless developer experience by automatically translating error messages without requiring changes to application logic. Currently at v3.0.0, this package regularly releases patch updates for new language support and minor fixes, with major versions tied to significant updates in its peer dependency, `better-auth`. Key features include multi-language support, automatic error message translation, full TypeScript type safety with autocomplete for custom translations, a robust fallback system for missing translations, flexible locale detection strategies (e.g., from headers, cookies, or database), and zero runtime overhead as translations are bundled at build time. It differentiates itself by tightly integrating with the `better-auth` ecosystem to provide a specialized localization solution.

auth-security serialization

npm install better-auth-localization

github ↗package ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-LOCALI

better-auth-localization

auth-securityjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

localization

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

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

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

LocalizationPluginOptions

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

✗ import { 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

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

✗ 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.

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

Debug

Known issues

breakingVersion 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.

affects: >=3.0.0

gotchaThe `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).

affects: >=2.2.0

gotchaPrior 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.

affects: <2.1.6

gotchaThe `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`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: betterAuth is not a function

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.

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)

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'.

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.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

better-authrequiredCore dependency for `better-auth` plugin system and error messages.

@better-auth/api-keyoptionalPeer dependency for localizing API key plugin specific error messages.

@better-auth/passkeyoptionalPeer dependency for localizing passkey plugin specific error messages.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/marcellosso/better-auth-localization ↗

packagehttps://www.npmjs.com/package/better-auth-localization ↗