i18n

i18n 插件允许你根据用户的语言环境翻译 Better Auth 返回的错误信息。它支持多种语言环境检测策略，包括 HTTP 头部、Cookie、会话数据和自定义回调函数。

Better Auth 默认已经提供了英文错误信息，所以你只需要提供其他语言的翻译。

安装

npm install @better-auth/i18n

import { betterAuth } from "better-auth"
import { i18n } from "@better-auth/i18n"

export const auth = betterAuth({
    plugins: [
        i18n({
            translations: {
                fr: {
                    USER_NOT_FOUND: "Utilisateur non trouvé",
                    INVALID_EMAIL_OR_PASSWORD: "Email ou mot de passe invalide",
                    INVALID_PASSWORD: "Mot de passe invalide",
                },
                de: {
                    USER_NOT_FOUND: "Benutzer nicht gefunden",
                    INVALID_EMAIL_OR_PASSWORD: "Ungültige E-Mail oder Passwort",
                    INVALID_PASSWORD: "Ungültiges Passwort",
                },
            },
        }),
    ],
})

使用说明

插件会自动检测用户的语言环境并相应地翻译错误信息。当返回错误时，响应中会同时包含翻译后的信息和原始信息。

错误响应格式

当发生错误且有可用的翻译时，响应内容如下：

{
    "code": "INVALID_EMAIL_OR_PASSWORD",
    "message": "Email ou mot de passe invalide",
    "originalMessage": "Invalid email or password"
}

语言环境检测

默认情况下，插件会从 Accept-Language HTTP 头部检测语言环境。你可以配置多种检测策略，按照顺序依次检测：

i18n({
    translations: { /* ... */ },
    detection: ["cookie", "header", "session"], // 检测优先级顺序
})

可用的检测策略有：

• header - 使用 Accept-Language HTTP 头部（默认）
• cookie - 从 Cookie 中读取语言环境
• session - 从认证用户存储的偏好中读取语言环境
• callback - 使用自定义函数确定语言环境

基于 Header 的检测

插件会自动解析 Accept-Language 头部，包括质量值：

Accept-Language: fr-CA, fr;q=0.9, en;q=0.8

这将依次尝试 fr-CA（映射为 fr）、fr、然后 en。

基于 Cookie 的检测

要使用基于 Cookie 的检测，请在检测策略中添加 "cookie"，并可选配置 Cookie 名称：

i18n({
    translations: { /* ... */ },
    detection: ["cookie", "header"],
    localeCookie: "lang", // 默认为 "locale"
})

基于会话的检测

如果你将用户的语言偏好存储在其资料中，可以通过会话检测：

export const auth = betterAuth({
    user: {
        additionalFields: {
            locale: { type: "string", required: false },
        },
    },
    plugins: [
        i18n({
            translations: { /* ... */ },
            detection: ["session", "header"],
            userLocaleField: "locale", // 默认为 "locale"
        }),
    ],
})

自定义检测回调

对于高级用例，你可以提供自定义语言环境检测函数：

i18n({
    translations: { /* ... */ },
    detection: ["callback", "header"],
    getLocale: (ctx) => {
        // 自定义逻辑：使用查询参数、自定义头部等
        if (!ctx.request) return null;
        const url = new URL(ctx.request.url);
        return url.searchParams.get("lang");
    },
})

回调函数会接收完整的端点上下文。应返回语言代码或者 null。

错误代码

插件基于错误代码来翻译错误信息。你可以在 错误代码参考 查找所有可用的错误代码。

常见错误代码包括：

选项

translations

类型: Record<string, Record<string, string>>

必填: 是

一个以语言代码为键的翻译字典。每个语言包含错误代码到翻译信息的映射。由于 Better Auth 已经提供英文信息，通常只需提供其他语言的翻译。

translations: {
    fr: { USER_NOT_FOUND: "Utilisateur non trouvé" },
    de: { USER_NOT_FOUND: "Benutzer nicht gefunden" },
}

defaultLocale

类型: string

默认: "en"（如果可能），否则为翻译字典中的第一个语言

当无法检测到语言环境或检测到的语言环境不在翻译字典中时使用的回退语言。

detection

类型: Array<"header" | "cookie" | "session" | "callback">

默认: ["header"]

语言环境检测策略数组，按优先级顺序。第一个返回有效语言的策略将被采用。

localeCookie

类型: string

默认: "locale"

使用 "cookie" 策略时读取的 Cookie 名称。

userLocaleField

类型: string

默认: "locale"

使用 "session" 策略时，存储用户语言环境偏好的用户字段名。

getLocale

类型: (ctx: GenericEndpointContext) => string | null | Promise<string | null>

使用 "callback" 策略时调用的自定义语言环境检测函数。接收完整端点上下文，返回语言代码或 null。

回退行为

• 如果在检测到的语言中找不到特定错误代码的翻译，则保留内置的英文信息。
• 如果检测到的语言环境不在翻译字典中，则使用内置的英文信息。
• 如果任何策略都无法检测到语言环境，则使用内置的英文信息。
• 非错误响应不会被此插件修改。