{"id":16769,"library":"better-auth-localization","title":"Better Auth Localization Plugin","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/marcellosso/better-auth-localization","tags":["javascript","better-auth","better-localization","better-auth-localization","localization","i18n","internationalization","translation","language","typescript"],"install":[{"cmd":"npm install better-auth-localization","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-localization","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-localization","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for `better-auth` plugin system and error messages.","package":"better-auth","optional":false},{"reason":"Peer dependency for localizing API key plugin specific error messages.","package":"@better-auth/api-key","optional":true},{"reason":"Peer dependency for localizing passkey plugin specific error messages.","package":"@better-auth/passkey","optional":true}],"imports":[{"note":"This package is designed for ESM environments, particularly when integrated with `better-auth`. Use named imports.","wrong":"const localization = require('better-auth-localization');","symbol":"localization","correct":"import { localization } from 'better-auth-localization';"},{"note":"Use `import type` for type-only imports to ensure they are stripped during compilation, especially important in TypeScript projects.","wrong":"import { LocalizationPluginOptions } from 'better-auth-localization';","symbol":"LocalizationPluginOptions","correct":"import type { LocalizationPluginOptions } from 'better-auth-localization';"},{"note":"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.","wrong":"import betterAuth from 'better-auth';","symbol":"betterAuth","correct":"import { betterAuth } from 'better-auth';"}],"quickstart":{"code":"import { betterAuth } from 'better-auth';\nimport { localization } from 'better-auth-localization';\n\n// Example: Simulate a basic better-auth config\nconst exampleConfig = {\n  secret: process.env.AUTH_SECRET ?? 'super-secret-development-key',\n  cookie: {\n    secure: process.env.NODE_ENV === 'production'\n  }\n};\n\nexport const auth = betterAuth({\n  ...exampleConfig,\n  plugins: [\n    localization({\n      defaultLocale: 'pt-BR', // Use built-in Portuguese translations\n      fallbackLocale: 'default', // Fallback to English\n      // For dynamic locale detection, you would add a getLocale function here:\n      // getLocale: async (req) => {\n      //   // Imagine reading locale from a cookie or header\n      //   const cookieHeader = (req as any)?.headers?.get(\"cookie\");\n      //   const cookies = cookieHeader ? Object.fromEntries(cookieHeader.split('; ').map(c => c.split('='))) : {};\n      //   return cookies.locale ?? 'default';\n      // }\n    })\n  ]\n});\n\n// To demonstrate usage (this part is illustrative and not part of the quickstart plugin setup):\n// try {\n//   // Simulate an authentication call that might throw an error\n//   // const user = await auth.signIn('test@example.com', 'wrong-password');\n// } catch (error: any) {\n//   console.log('Localized error:', error.message); // Should output translated message\n// }","lang":"typescript","description":"Initializes `better-auth` with the `localization` plugin, setting a default locale and a fallback. This demonstrates basic integration."},"warnings":[{"fix":"Update `better-auth` to `>=1.5.0` in your project's `package.json` and reinstall dependencies.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=2.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.1.6"},{"fix":"Ensure `localization(...)` is added to the `plugins: [...]` array when initializing `betterAuth`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change `import betterAuth from 'better-auth';` to `import { betterAuth } from 'better-auth';`","cause":"Attempting to use `betterAuth` as a default import instead of a named import.","error":"TypeError: betterAuth is not a function"},{"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`.","cause":"Your installed `better-auth` version does not satisfy the `better-auth-localization` v3.x requirement.","error":"Error: Peer dependency better-auth@^1.5.0 not met."},{"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.","cause":"Localization plugin is not configured or activated, or the requested locale is not found and no fallback is provided.","error":"Error: USER_NOT_FOUND (or similar untranslated error message)"},{"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.","cause":"Potential type mismatch for the `Request` object passed to `getLocale` when integrating with specific web frameworks or custom server setups.","error":"Type 'Request' is not assignable to type 'Request'."}],"ecosystem":"npm","meta_description":null}