@tanosugi/better-auth-utils/dist/plugin-localization.d.mts

Better Auth Utils

declare const allowedLocales: readonly ["en", "ja", "fr", "de", "es", "it", "nl", "pl", "pt", "ru", "th", "tr", "uk", "zh-CN", "zh-TW", "ko", "id", "hi", "cs", "ar", "all"];
type Locale = (typeof allowedLocales)[number];
type SimpleDict = Record<string, string>;
type MultiLangDict = Record<string, Partial<Record<Locale, string>>>;
type TFunc = (locale: string) => Promise<(key: string) => string>;
type SimpleDictWithTFunc = (t: (key: string) => string) => Record<string, string>;
type LocalizationOptionsExt = ({
    enabledLocales: Locale[];
    i18nRouting?: never;
    singleLang?: never;
} & LocalizationOptionsCommon) | ({
    enabledLocales?: never;
    i18nRouting: Locale[];
    singleLang?: never;
} & LocalizationOptionsCommon) | ({
    enabledLocales?: never;
    i18nRouting?: never;
    singleLang: Exclude<Locale, "all">;
} & LocalizationOptionsCommon) | ({
    enabledLocales?: never;
    i18nRouting?: never;
    singleLang?: never;
} & LocalizationOptionsCommon);
type LocalizationOptionsCommon = {
    simpleDict?: SimpleDict;
    multiLangDict?: MultiLangDict;
} & ({
    simpleDictWithTFunc: SimpleDictWithTFunc;
    tFuncServer: (locale: string) => Promise<(key: string) => string>;
} | {
    simpleDictWithTFunc?: undefined;
    tFuncServer?: undefined;
});
/**
 * getLang(ctx, options)
 * Determines the language to use based on the request context and localization options.
 * @param ctx - The request context (should have acceptLanguage and referer properties)
 * @param options - Localization options (enabledLocales, i18nRouting, or singleLang)
 * @returns {Locale | undefined} - The detected locale or undefined if not found
 *
 * Usage:
 *   const lang = getLang(ctx, options);
 */
declare function getLang(ctx: any, options?: LocalizationOptionsExt): Locale | undefined;
/**
 * getLocalizedMessage(lang, code)
 * Returns the localized message string for the given language and code.
 * @param lang - The language code (e.g., 'en', 'ja')
 * @param code - The message code/key
 * @returns {string | undefined} - The localized message or undefined if not found
 *
 * Usage:
 *   const message = getLocalizedMessage('en', 'LOGIN_SUCCESS');
 */
declare function getLocalizedMessage(lang: string | undefined, code: string | undefined): string | undefined;
declare function generateDictWithT(simpleDictWithTFunc: SimpleDictWithTFunc, tFuncServer: (locale: string) => Promise<(key: string) => string>, locale: string): Promise<Record<string, string>>;
/**
 * localization(options)
 * Returns a BetterAuthPlugin for localization, handling request and response localization.
 *
 * @param {Object} options - Localization options object (optional)
 * @param {Record<string, string>} [options.simpleDict] - Key-value pairs to merge into all languages.
 * @param {Record<string, Partial<Record<Locale, string>>>} [options.multiLangDict] - Per-language
 *   message dictionary for each code.
 * @param {Locale[]} [options.enabledLocales] - Array of allowed locales. "all" allows all supported locales.
 * @param {Locale[]} [options.i18nRouting] - Locales to detect from the first path segment of the referer URL.
 * @param {Exclude<Locale, "all">} [options.singleLang] - Always use this language for localization.
 *
 * @returns {BetterAuthPlugin} - The localization plugin object with onRequest and onResponse hooks.
 *
 * Usage:
 *   // Example 1: No arguments (default behavior)
 *   plugins: [localization()],
 *   // Uses Accept-Language header to determine the language and translate.
 *
 *   // Example 2: singleLang
 *   plugins: [localization({
 *     singleLang: "ja"
 *   })],
 *   // Always uses Japanese for localization, regardless of request headers or URL.
 *
 *   // Example 3: enabledLocales and multiLangDict (multiple languages)
 *   plugins: [localization({
 *     enabledLocales: ["en", "ja", "fr"],
 *     simpleDict: { LOGIN_SUCCESS: "Login successful!" },
 *     multiLangDict: {
 *       LOGIN_SUCCESS: {
 *         en: "Login successful!",
 *         ja: "ログイン成功！",
 *         fr: "Connexion réussie !"
 *       }
 *     }
 *   })],
 *   // The message will be translated based on Accept-Language header but limited to the enabledLocales.
 *   // simpleDict and multiLangDict are used with priority over default translations.
 *
 *   // Example 4: i18nRouting
 *   plugins: [localization({
 *     i18nRouting: ["en", "ja"],
 *     simpleDict: {
 *       LOGIN_SUCCESS: "Login successful!"
 *     }
 *   })],
 *   // The language is determined from the first path segment of the referer URL.
 *
 *   // Example 5: simpleDictWithTFunc and tFuncServer (for dynamic translation)
 *   plugins: [localization({
 *     i18nRouting: ["en", "ja"],
 *     simpleDictWithTFunc: (t) => ({ EMAIL_NOT_VERIFIED: t("Email not verified!!") }),
 *     tFuncServer: async (locale) => {
 *       const t = await getTranslations({ locale });
 *       return (key) => t(key);
 *     },
 *   })],
 *   // Used for i18n routing such as next-intl.
 *   // The message will be dynamically translated using the t function for the current locale.
 *
 *   // Use plugin.onRequest and plugin.onResponse in your auth flow
 */
declare const localization: (options?: LocalizationOptionsExt) => {
    id: "localization";
    onRequest(req: Request, ctx: any): Promise<void>;
    onResponse: (response: Response, ctx: any) => Promise<{
        response: Response;
    }>;
};

export { type LocalizationOptionsCommon, type LocalizationOptionsExt, type MultiLangDict, type SimpleDict, type SimpleDictWithTFunc, type TFunc, generateDictWithT, getLang, getLocalizedMessage, localization };