的認(rèn)證錯(cuò)誤消息國(guó)際化方案)
Better Auth i18n 插件完全指南基于語言檢測(cè)的認(rèn)證錯(cuò)誤消息國(guó)際化方案【免費(fèi)下載鏈接】better-authThe most comprehensive authentication framework項(xiàng)目地址: https://gitcode.com/GitHub_Trending/be/better-auth導(dǎo)讀better-auth/i18n是 Better Auth 官方提供的國(guó)際化i18n插件用于根據(jù)檢測(cè)到的用戶語言區(qū)域locale自動(dòng)翻譯認(rèn)證接口返回的錯(cuò)誤消息例如把INVALID_EMAIL_OR_PASSWORD從英文 Invalid email or password 翻譯為法文、德文或中文。本文以 packages/i18n/README.md 為骨架結(jié)合 插件核心實(shí)現(xiàn)、類型定義 與 完整測(cè)試用例完整講解插件的安裝、四種語言檢測(cè)策略、全部配置項(xiàng)以及源碼級(jí)工作原理幫助你在一鍵啟用 22 種內(nèi)置語言的同時(shí)掌握自定義翻譯與兜底機(jī)制的實(shí)戰(zhàn)技巧。一、安裝better-auth/i18n是一個(gè)獨(dú)立的 npm 包與better-auth主框架配合使用可通過 pnpm / npm / yarn 安裝npm install better-auth/i18n從 packages/i18n/package.json 可以看到該包聲明better-auth與better-auth/core為 peerDependenciesworkspace:^即它必須與 Better Auth 核心框架在同一項(xiàng)目中共同使用包本身以 ESM 形式發(fā)布main/module均指向./dist/index.mjs并提供了三個(gè)導(dǎo)出入口.主入口導(dǎo)出i18n插件工廠與locales內(nèi)置語言集合./client客戶端入口導(dǎo)出i18nClient用于在createAuthClient中獲得服務(wù)端插件的類型推斷./locales單獨(dú)導(dǎo)出全部?jī)?nèi)置翻譯字典。當(dāng)前倉(cāng)庫(kù)中該包的版本為1.7.3見 CHANGELOG.md22 種內(nèi)置語言在 1.7.0 版本引入。二、內(nèi)置翻譯開箱即用的 22 種語言插件隨包攜帶 22 種語言的完整翻譯字典覆蓋了全球主要語種。全部語言文件位于 packages/i18n/src/locales/并通過 locales/index.ts 統(tǒng)一導(dǎo)出| 代碼 | 語言 | | 代碼 | 語言 | |------|------|-|------|------| |ar| 阿拉伯語 | |nl| 荷蘭語 | |bn| 孟加拉語 | |pl| 波蘭語 | |de| 德語 | |pt| 葡萄牙語 | |en| 英語 | |ru| 俄語 | |es| 西班牙語 | |sv| 瑞典語 | |fa| 波斯語法爾西語 | |th| 泰語 | |fr| 法語 | |tr| 土耳其語 | |hi| 印地語 | |uk| 烏克蘭語 | |id| 印度尼西亞語 | |vi| 越南語 | |it| 意大利語 | |zh| 簡(jiǎn)體中文 | |ja| 日語 | |ko| 韓語 |每種語言都是一個(gè)TranslationDictionary對(duì)象。以 英文默認(rèn)字典 為例它覆蓋了 34 個(gè)核心錯(cuò)誤碼包括USER_NOT_FOUND、INVALID_EMAIL_OR_PASSWORD、PASSWORD_TOO_SHORT、TOKEN_EXPIRED、EMAIL_NOT_VERIFIED、SESSION_EXPIRED、ACCOUNT_NOT_FOUND等認(rèn)證場(chǎng)景中的高頻錯(cuò)誤。簡(jiǎn)體中文翻譯見 zh.ts例如INVALID_EMAIL_OR_PASSWORD對(duì)應(yīng)郵箱或密碼無效SESSION_EXPIRED對(duì)應(yīng)會(huì)話已過期請(qǐng)重新驗(yàn)證身份以執(zhí)行此操作。從測(cè)試用例 i18n.test.ts 可以確認(rèn)項(xiàng)目對(duì)每種內(nèi)置語言都做了完整性校驗(yàn)USER_NOT_FOUND、INVALID_PASSWORD、INVALID_EMAIL、INVALID_EMAIL_OR_PASSWORD、EMAIL_NOT_VERIFIED、PASSWORD_TOO_SHORT、PASSWORD_TOO_LONG、USER_ALREADY_EXISTS、SESSION_EXPIRED、ACCOUNT_NOT_FOUND這 10 個(gè)關(guān)鍵錯(cuò)誤碼必須存在于所有語言字典中且值必須是非空字符串。使用全部?jī)?nèi)置語言在betterAuth配置中掛載插件translations直接傳入locales即可啟用全部 22 種語言import { betterAuth } from better-auth; import { i18n, locales } from better-auth/i18n; export const auth betterAuth({ plugins: [ i18n({ translations: locales }), ], });使用語言子集如果只需要服務(wù)特定市場(chǎng)可以只挑選部分語言減小打包體積import { i18n, locales } from better-auth/i18n; export const auth betterAuth({ plugins: [ i18n({ translations: { en: locales.en, fr: locales.fr, }, }), ], });注意translations中實(shí)際提供的語言代碼就是插件可識(shí)別的全部語言集合——檢測(cè)到不在集合中的語言時(shí)會(huì)回退到默認(rèn)語言詳見下文語言檢測(cè)與兜底。三、覆蓋與擴(kuò)展翻譯覆蓋特定錯(cuò)誤消息當(dāng)某個(gè)內(nèi)置翻譯不符合你的產(chǎn)品文案風(fēng)格時(shí)可以基于內(nèi)置字典做淺合并覆蓋無需重建整個(gè)字典import { i18n, locales } from better-auth/i18n; export const auth betterAuth({ plugins: [ i18n({ translations: { ...locales, fr: { ...locales.fr, USER_NOT_FOUND: Membre introuvable, }, }, }), ], });添加自定義語言TranslationDictionary的類型是Partial錯(cuò)誤碼集合 Recordstring, string見 types.ts即除了內(nèi)置錯(cuò)誤碼你還可以為插件擴(kuò)展的其他錯(cuò)誤碼提供翻譯甚至加入自己的自定義鍵import { i18n, locales } from better-auth/i18n; import type { TranslationDictionary } from better-auth/i18n; const myLocale: TranslationDictionary { USER_NOT_FOUND: ..., INVALID_EMAIL_OR_PASSWORD: ..., // ... 其他錯(cuò)誤碼 }; export const auth betterAuth({ plugins: [ i18n({ translations: { ...locales, xx: myLocale, }, }), ], });值得說明的是TranslationDictionary通過UnionToIntersection類型體操自動(dòng)聚合了 Better Auth 插件注冊(cè)表中所有插件聲明的錯(cuò)誤碼見 types.ts因此當(dāng)你同時(shí)使用其他插件如組織、API Key 等并為其聲明了$ERROR_CODES時(shí)自定義字典會(huì)獲得這些錯(cuò)誤碼的完整類型提示在編譯期就能發(fā)現(xiàn)遺漏。四、語言檢測(cè)策略header / cookie / session / callback插件根據(jù)detection數(shù)組中的策略按優(yōu)先級(jí)順序逐一嘗試檢測(cè)用戶語言命中即返回。支持四種策略見 types.ts其實(shí)現(xiàn)全部位于 src/index.ts策略說明檢測(cè)來源header解析請(qǐng)求的Accept-Language頭ctx.headerscookie讀取指定名稱的 Cookie 值Cookie頭session讀取當(dāng)前會(huì)話用戶記錄中的語言字段ctx.context.session.usercallback調(diào)用自定義的getLocale函數(shù)用戶自定義邏輯1. header默認(rèn)策略默認(rèn)配置下插件只啟用header策略。它會(huì)先調(diào)用內(nèi)部的parseAcceptLanguage函數(shù)src/index.ts解析Accept-Language頭按;拆分出每個(gè)語言及其q質(zhì)量值按質(zhì)量值降序排序并把形如fr-CA的區(qū)域碼裁剪為基礎(chǔ)語言碼fr然后返回第一個(gè)存在于translations中的語言。例如請(qǐng)求頭Accept-Language: es;q0.9, fr;q0.8, en;q0.7而你的translations只有 en/fr/de 時(shí)檢測(cè)結(jié)果會(huì)是fr因?yàn)閑s不在支持集合內(nèi)測(cè)試見 i18n.test.ts請(qǐng)求頭fr-CA也會(huì)正確落到fr測(cè)試見 i18n.test.ts。2. cookie當(dāng)用戶在應(yīng)用內(nèi)手動(dòng)切換語言時(shí)通常希望把選擇持久化到 Cookie。啟用cookie策略后插件會(huì)解析Cookie頭并讀取localeCookie指定的 Cookie默認(rèn)名為locale若其值在支持的語言集合中則采用i18n({ translations: { en: locales.en, fr: locales.fr }, detection: [cookie, header], // cookie 優(yōu)先header 兜底 localeCookie: lang, // 自定義 Cookie 名稱 })測(cè)試用例驗(yàn)證了優(yōu)先級(jí)行為當(dāng)Cookie: langfr且Accept-Language: de同時(shí)存在、detection順序?yàn)閇cookie, header]時(shí)最終使用 Cookie 中的法語見 i18n.test.ts。3. session對(duì)于登錄用戶可以直接讀取用戶資料中保存的語言偏好。插件從ctx.context.session.user中讀取userLocaleField指定的字段默認(rèn)字段名也是locale。這意味著你可以在用戶表上擴(kuò)展一個(gè)locale字段讓用戶的語言選擇跟隨賬號(hào)跨設(shè)備同步。4. callbackcallback策略提供最大靈活性它調(diào)用getLocale(ctx)函數(shù)你可以從任意來源決定語言例如自定義請(qǐng)求頭、子域名或數(shù)據(jù)庫(kù)查詢i18n({ translations: { en: locales.en, fr: locales.fr }, detection: [callback], getLocale: (ctx) { return ctx.headers?.get(X-Custom-Locale) ?? null; }, })從測(cè)試可見getLocale既支持同步返回值也支持Promise見 types.ts并且即使請(qǐng)求對(duì)象未定義如直接調(diào)用auth.api的場(chǎng)景回調(diào)仍會(huì)被正常調(diào)用見 i18n.test.ts。五、完整配置項(xiàng)一覽所有配置項(xiàng)匯總?cè)缦戮鶃碜?types.ts 與 src/index.ts 的默認(rèn)值合并邏輯配置項(xiàng)類型默認(rèn)值說明translations{ [locale]: TranslationDictionary }必填語言代碼到翻譯字典的映射為空時(shí)插件直接拋出i18n plugin: translations object is empty錯(cuò)誤測(cè)試見 i18n.test.tsdefaultLocalestringen所有檢測(cè)策略都失敗時(shí)使用的兜底語言。規(guī)則顯式指定且存在于translations時(shí)優(yōu)先使用否則若集合中有en則用enen也不存在時(shí)使用集合中第一個(gè)語言detectionLocaleDetectionStrategy[][header]語言檢測(cè)策略數(shù)組按數(shù)組順序依次嘗試第一個(gè)命中即生效localeCookiestringlocalecookie策略讀取的 Cookie 名稱userLocaleFieldstringlocalesession策略讀取的用戶字段名getLocale(ctx) string \| null \| Promise...無callback策略使用的自定義檢測(cè)函數(shù)defaultLocale的解析邏輯見 src/index.ts它優(yōu)先采納顯式傳入且存在于翻譯集合中的值否則當(dāng)集合包含en時(shí)回退為enen缺失時(shí)采用集合中第一個(gè)語言。測(cè)試用例覆蓋了這三種情況以及未提供defaultLocale且無en時(shí)保持原始英文消息的行為見 i18n.test.ts。六、工作原理after 鉤子 APIError 重拋了解插件如何翻譯錯(cuò)誤有助于你排查自定義場(chǎng)景。插件實(shí)現(xiàn)位于 src/index.ts它注冊(cè)了一個(gè)匹配所有請(qǐng)求的after鉤子攔截錯(cuò)誤響應(yīng)從ctx.context.returned取出請(qǐng)求返回結(jié)果僅當(dāng)它是APIErrorisAPIError判斷時(shí)才繼續(xù)處理——正常響應(yīng)、非錯(cuò)誤響應(yīng)直接跳過測(cè)試驗(yàn)證了成功響應(yīng)不會(huì)被改動(dòng)見 i18n.test.ts提取錯(cuò)誤碼從錯(cuò)誤體returned.body中取出code字符串這是后續(xù)查字典的鍵檢測(cè)語言調(diào)用detectLocale(ctx)按detection順序解析當(dāng)前請(qǐng)求的語言查字典并重拋在opts.translations[locale]?.[errorCode]中查找翻譯。若找到則用原 HTTP 狀態(tài)碼和錯(cuò)誤碼重新拋出一個(gè)APIError新錯(cuò)誤體包含三個(gè)字段code原始錯(cuò)誤碼保持不變message翻譯后的本地化消息originalMessage翻譯前的原始英文消息便于調(diào)試與日志記錄。若找不到對(duì)應(yīng)翻譯例如該錯(cuò)誤碼未收錄則保持原樣返回不進(jìn)行任何修改見 i18n.test.ts 的兜底行為驗(yàn)證。由于翻譯發(fā)生在服務(wù)端統(tǒng)一的after鉤子中所有認(rèn)證端點(diǎn)登錄、注冊(cè)、找回密碼、會(huì)話校驗(yàn)等的錯(cuò)誤消息都會(huì)自動(dòng)本地化客戶端無需改動(dòng)任何請(qǐng)求邏輯。七、客戶端類型推斷i18nClient雖然翻譯完全在服務(wù)端完成官方仍建議在客戶端同步掛載i18nClient以獲得服務(wù)端插件配置的類型推斷例如$InferServerPlugin帶來的端到端類型安全import { createAuthClient } from better-auth/client; import { i18nClient } from better-auth/i18n/client; export const client createAuthClient({ plugins: [i18nClient()], });客戶端實(shí)現(xiàn)見 src/client.ts它聲明了與服務(wù)端相同的插件id: i18n并通過$InferServerPlugin完成類型關(guān)聯(lián)。注意客戶端不承擔(dān)翻譯邏輯——錯(cuò)誤消息已經(jīng)由服務(wù)端按檢測(cè)到的語言翻譯完畢客戶端插件只負(fù)責(zé)類型層面的銜接。八、驗(yàn)證與測(cè)試倉(cāng)庫(kù)為插件提供了覆蓋全面的單元測(cè)試 i18n.test.ts共覆蓋八個(gè)維度基于Accept-Language頭的檢測(cè)法語、德語、質(zhì)量值排序、fr-CA基礎(chǔ)碼裁剪、不可用語言回退基于 Cookie 的檢測(cè)及其與 header 的優(yōu)先級(jí)翻譯缺失時(shí)的兜底行為getLocale回調(diào)檢測(cè)及無請(qǐng)求場(chǎng)景非錯(cuò)誤響應(yīng)不被改動(dòng)defaultLocale的三種解析分支與空翻譯集合報(bào)錯(cuò)內(nèi)置語言的完整性22 個(gè)語言全部導(dǎo)出、10 個(gè)關(guān)鍵錯(cuò)誤碼非空。你可以在倉(cāng)庫(kù)根目錄運(yùn)行對(duì)應(yīng)包測(cè)試來驗(yàn)證當(dāng)前行為pnpm --filter better-auth/i18n test總結(jié)better-auth/i18n用極低的接入成本一個(gè)插件、一個(gè)translations配置為 Better Auth 的認(rèn)證錯(cuò)誤消息提供了完整的國(guó)際化能力22 種內(nèi)置語言開箱即用header/cookie/session/callback四種檢測(cè)策略覆蓋從瀏覽器自動(dòng)匹配到用戶手動(dòng)選擇、跨設(shè)備同步的全部場(chǎng)景defaultLocale與翻譯缺失保持原文的雙重兜底機(jī)制保證了任何情況下接口都不會(huì)出現(xiàn)空消息。若需深度定制TranslationDictionary類型會(huì)隨插件注冊(cè)表自動(dòng)聚合錯(cuò)誤碼配合getLocale回調(diào)你可以將任何自定義語言檢測(cè)邏輯無縫接入認(rèn)證流程。【免費(fèi)下載鏈接】better-authThe most comprehensive authentication framework項(xiàng)目地址: https://gitcode.com/GitHub_Trending/be/better-auth創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Better Auth i18n 插件完全指南：基于語言檢測(cè)的認(rèn)證錯(cuò)誤消息國(guó)際化方案
Better Auth i18n 插件完全指南基于語言檢測(cè)的認(rèn)證錯(cuò)誤消息國(guó)際化方案【免費(fèi)下載鏈接】better-authThe most comprehensive authentication framework項(xiàng)目地址: https://gitcode.com/GitHub_Trending/be/better-auth導(dǎo)讀better-auth/i18n是 Better Auth 官方提供的國(guó)際化i18n插件用于根據(jù)檢測(cè)到的用戶語言區(qū)域locale自動(dòng)翻譯認(rèn)證接口返回的錯(cuò)誤消息例如把INVALID_EMAIL_OR_PASSWORD從英文 Invalid email or password 翻譯為法文、德文或中文。本文以 packages/i18n/README.md 為骨架結(jié)合 插件核心實(shí)現(xiàn)、類型定義 與 完整測(cè)試用例完整講解插件的安裝、四種語言檢測(cè)策略、全部配置項(xiàng)以及源碼級(jí)工作原理幫助你在一鍵啟用 22 種內(nèi)置語言的同時(shí)掌握自定義翻譯與兜底機(jī)制的實(shí)戰(zhàn)技巧。一、安裝better-auth/i18n是一個(gè)獨(dú)立的 npm 包與better-auth主框架配合使用可通過 pnpm / npm / yarn 安裝npm install better-auth/i18n從 packages/i18n/package.json 可以看到該包聲明better-auth與better-auth/core為 peerDependenciesworkspace:^即它必須與 Better Auth 核心框架在同一項(xiàng)目中共同使用包本身以 ESM 形式發(fā)布main/module均指向./dist/index.mjs并提供了三個(gè)導(dǎo)出入口.主入口導(dǎo)出i18n插件工廠與locales內(nèi)置語言集合./client客戶端入口導(dǎo)出i18nClient用于在createAuthClient中獲得服務(wù)端插件的類型推斷./locales單獨(dú)導(dǎo)出全部?jī)?nèi)置翻譯字典。當(dāng)前倉(cāng)庫(kù)中該包的版本為1.7.3見 CHANGELOG.md22 種內(nèi)置語言在 1.7.0 版本引入。二、內(nèi)置翻譯開箱即用的 22 種語言插件隨包攜帶 22 種語言的完整翻譯字典覆蓋了全球主要語種。全部語言文件位于 packages/i18n/src/locales/并通過 locales/index.ts 統(tǒng)一導(dǎo)出| 代碼 | 語言 | | 代碼 | 語言 | |------|------|-|------|------| |ar| 阿拉伯語 | |nl| 荷蘭語 | |bn| 孟加拉語 | |pl| 波蘭語 | |de| 德語 | |pt| 葡萄牙語 | |en| 英語 | |ru| 俄語 | |es| 西班牙語 | |sv| 瑞典語 | |fa| 波斯語法爾西語 | |th| 泰語 | |fr| 法語 | |tr| 土耳其語 | |hi| 印地語 | |uk| 烏克蘭語 | |id| 印度尼西亞語 | |vi| 越南語 | |it| 意大利語 | |zh| 簡(jiǎn)體中文 | |ja| 日語 | |ko| 韓語 |每種語言都是一個(gè)TranslationDictionary對(duì)象。以 英文默認(rèn)字典 為例它覆蓋了 34 個(gè)核心錯(cuò)誤碼包括USER_NOT_FOUND、INVALID_EMAIL_OR_PASSWORD、PASSWORD_TOO_SHORT、TOKEN_EXPIRED、EMAIL_NOT_VERIFIED、SESSION_EXPIRED、ACCOUNT_NOT_FOUND等認(rèn)證場(chǎng)景中的高頻錯(cuò)誤。簡(jiǎn)體中文翻譯見 zh.ts例如INVALID_EMAIL_OR_PASSWORD對(duì)應(yīng)郵箱或密碼無效SESSION_EXPIRED對(duì)應(yīng)會(huì)話已過期請(qǐng)重新驗(yàn)證身份以執(zhí)行此操作。從測(cè)試用例 i18n.test.ts 可以確認(rèn)項(xiàng)目對(duì)每種內(nèi)置語言都做了完整性校驗(yàn)USER_NOT_FOUND、INVALID_PASSWORD、INVALID_EMAIL、INVALID_EMAIL_OR_PASSWORD、EMAIL_NOT_VERIFIED、PASSWORD_TOO_SHORT、PASSWORD_TOO_LONG、USER_ALREADY_EXISTS、SESSION_EXPIRED、ACCOUNT_NOT_FOUND這 10 個(gè)關(guān)鍵錯(cuò)誤碼必須存在于所有語言字典中且值必須是非空字符串。使用全部?jī)?nèi)置語言在betterAuth配置中掛載插件translations直接傳入locales即可啟用全部 22 種語言import { betterAuth } from better-auth; import { i18n, locales } from better-auth/i18n; export const auth betterAuth({ plugins: [ i18n({ translations: locales }), ], });使用語言子集如果只需要服務(wù)特定市場(chǎng)可以只挑選部分語言減小打包體積import { i18n, locales } from better-auth/i18n; export const auth betterAuth({ plugins: [ i18n({ translations: { en: locales.en, fr: locales.fr, }, }), ], });注意translations中實(shí)際提供的語言代碼就是插件可識(shí)別的全部語言集合——檢測(cè)到不在集合中的語言時(shí)會(huì)回退到默認(rèn)語言詳見下文語言檢測(cè)與兜底。三、覆蓋與擴(kuò)展翻譯覆蓋特定錯(cuò)誤消息當(dāng)某個(gè)內(nèi)置翻譯不符合你的產(chǎn)品文案風(fēng)格時(shí)可以基于內(nèi)置字典做淺合并覆蓋無需重建整個(gè)字典import { i18n, locales } from better-auth/i18n; export const auth betterAuth({ plugins: [ i18n({ translations: { ...locales, fr: { ...locales.fr, USER_NOT_FOUND: Membre introuvable, }, }, }), ], });添加自定義語言TranslationDictionary的類型是Partial錯(cuò)誤碼集合 Recordstring, string見 types.ts即除了內(nèi)置錯(cuò)誤碼你還可以為插件擴(kuò)展的其他錯(cuò)誤碼提供翻譯甚至加入自己的自定義鍵import { i18n, locales } from better-auth/i18n; import type { TranslationDictionary } from better-auth/i18n; const myLocale: TranslationDictionary { USER_NOT_FOUND: ..., INVALID_EMAIL_OR_PASSWORD: ..., // ... 其他錯(cuò)誤碼 }; export const auth betterAuth({ plugins: [ i18n({ translations: { ...locales, xx: myLocale, }, }), ], });值得說明的是TranslationDictionary通過UnionToIntersection類型體操自動(dòng)聚合了 Better Auth 插件注冊(cè)表中所有插件聲明的錯(cuò)誤碼見 types.ts因此當(dāng)你同時(shí)使用其他插件如組織、API Key 等并為其聲明了$ERROR_CODES時(shí)自定義字典會(huì)獲得這些錯(cuò)誤碼的完整類型提示在編譯期就能發(fā)現(xiàn)遺漏。四、語言檢測(cè)策略header / cookie / session / callback插件根據(jù)detection數(shù)組中的策略按優(yōu)先級(jí)順序逐一嘗試檢測(cè)用戶語言命中即返回。支持四種策略見 types.ts其實(shí)現(xiàn)全部位于 src/index.ts策略說明檢測(cè)來源header解析請(qǐng)求的Accept-Language頭ctx.headerscookie讀取指定名稱的 Cookie 值Cookie頭session讀取當(dāng)前會(huì)話用戶記錄中的語言字段ctx.context.session.usercallback調(diào)用自定義的getLocale函數(shù)用戶自定義邏輯1. header默認(rèn)策略默認(rèn)配置下插件只啟用header策略。它會(huì)先調(diào)用內(nèi)部的parseAcceptLanguage函數(shù)src/index.ts解析Accept-Language頭按;拆分出每個(gè)語言及其q質(zhì)量值按質(zhì)量值降序排序并把形如fr-CA的區(qū)域碼裁剪為基礎(chǔ)語言碼fr然后返回第一個(gè)存在于translations中的語言。例如請(qǐng)求頭Accept-Language: es;q0.9, fr;q0.8, en;q0.7而你的translations只有 en/fr/de 時(shí)檢測(cè)結(jié)果會(huì)是fr因?yàn)閑s不在支持集合內(nèi)測(cè)試見 i18n.test.ts請(qǐng)求頭fr-CA也會(huì)正確落到fr測(cè)試見 i18n.test.ts。2. cookie當(dāng)用戶在應(yīng)用內(nèi)手動(dòng)切換語言時(shí)通常希望把選擇持久化到 Cookie。啟用cookie策略后插件會(huì)解析Cookie頭并讀取localeCookie指定的 Cookie默認(rèn)名為locale若其值在支持的語言集合中則采用i18n({ translations: { en: locales.en, fr: locales.fr }, detection: [cookie, header], // cookie 優(yōu)先header 兜底 localeCookie: lang, // 自定義 Cookie 名稱 })測(cè)試用例驗(yàn)證了優(yōu)先級(jí)行為當(dāng)Cookie: langfr且Accept-Language: de同時(shí)存在、detection順序?yàn)閇cookie, header]時(shí)最終使用 Cookie 中的法語見 i18n.test.ts。3. session對(duì)于登錄用戶可以直接讀取用戶資料中保存的語言偏好。插件從ctx.context.session.user中讀取userLocaleField指定的字段默認(rèn)字段名也是locale。這意味著你可以在用戶表上擴(kuò)展一個(gè)locale字段讓用戶的語言選擇跟隨賬號(hào)跨設(shè)備同步。4. callbackcallback策略提供最大靈活性它調(diào)用getLocale(ctx)函數(shù)你可以從任意來源決定語言例如自定義請(qǐng)求頭、子域名或數(shù)據(jù)庫(kù)查詢i18n({ translations: { en: locales.en, fr: locales.fr }, detection: [callback], getLocale: (ctx) { return ctx.headers?.get(X-Custom-Locale) ?? null; }, })從測(cè)試可見getLocale既支持同步返回值也支持Promise見 types.ts并且即使請(qǐng)求對(duì)象未定義如直接調(diào)用auth.api的場(chǎng)景回調(diào)仍會(huì)被正常調(diào)用見 i18n.test.ts。五、完整配置項(xiàng)一覽所有配置項(xiàng)匯總?cè)缦戮鶃碜?types.ts 與 src/index.ts 的默認(rèn)值合并邏輯配置項(xiàng)類型默認(rèn)值說明translations{ [locale]: TranslationDictionary }必填語言代碼到翻譯字典的映射為空時(shí)插件直接拋出i18n plugin: translations object is empty錯(cuò)誤測(cè)試見 i18n.test.tsdefaultLocalestringen所有檢測(cè)策略都失敗時(shí)使用的兜底語言。規(guī)則顯式指定且存在于translations時(shí)優(yōu)先使用否則若集合中有en則用enen也不存在時(shí)使用集合中第一個(gè)語言detectionLocaleDetectionStrategy[][header]語言檢測(cè)策略數(shù)組按數(shù)組順序依次嘗試第一個(gè)命中即生效localeCookiestringlocalecookie策略讀取的 Cookie 名稱userLocaleFieldstringlocalesession策略讀取的用戶字段名getLocale(ctx) string \| null \| Promise...無callback策略使用的自定義檢測(cè)函數(shù)defaultLocale的解析邏輯見 src/index.ts它優(yōu)先采納顯式傳入且存在于翻譯集合中的值否則當(dāng)集合包含en時(shí)回退為enen缺失時(shí)采用集合中第一個(gè)語言。測(cè)試用例覆蓋了這三種情況以及未提供defaultLocale且無en時(shí)保持原始英文消息的行為見 i18n.test.ts。六、工作原理after 鉤子 APIError 重拋了解插件如何翻譯錯(cuò)誤有助于你排查自定義場(chǎng)景。插件實(shí)現(xiàn)位于 src/index.ts它注冊(cè)了一個(gè)匹配所有請(qǐng)求的after鉤子攔截錯(cuò)誤響應(yīng)從ctx.context.returned取出請(qǐng)求返回結(jié)果僅當(dāng)它是APIErrorisAPIError判斷時(shí)才繼續(xù)處理——正常響應(yīng)、非錯(cuò)誤響應(yīng)直接跳過測(cè)試驗(yàn)證了成功響應(yīng)不會(huì)被改動(dòng)見 i18n.test.ts提取錯(cuò)誤碼從錯(cuò)誤體returned.body中取出code字符串這是后續(xù)查字典的鍵檢測(cè)語言調(diào)用detectLocale(ctx)按detection順序解析當(dāng)前請(qǐng)求的語言查字典并重拋在opts.translations[locale]?.[errorCode]中查找翻譯。若找到則用原 HTTP 狀態(tài)碼和錯(cuò)誤碼重新拋出一個(gè)APIError新錯(cuò)誤體包含三個(gè)字段code原始錯(cuò)誤碼保持不變message翻譯后的本地化消息originalMessage翻譯前的原始英文消息便于調(diào)試與日志記錄。若找不到對(duì)應(yīng)翻譯例如該錯(cuò)誤碼未收錄則保持原樣返回不進(jìn)行任何修改見 i18n.test.ts 的兜底行為驗(yàn)證。由于翻譯發(fā)生在服務(wù)端統(tǒng)一的after鉤子中所有認(rèn)證端點(diǎn)登錄、注冊(cè)、找回密碼、會(huì)話校驗(yàn)等的錯(cuò)誤消息都會(huì)自動(dòng)本地化客戶端無需改動(dòng)任何請(qǐng)求邏輯。七、客戶端類型推斷i18nClient雖然翻譯完全在服務(wù)端完成官方仍建議在客戶端同步掛載i18nClient以獲得服務(wù)端插件配置的類型推斷例如$InferServerPlugin帶來的端到端類型安全import { createAuthClient } from better-auth/client; import { i18nClient } from better-auth/i18n/client; export const client createAuthClient({ plugins: [i18nClient()], });客戶端實(shí)現(xiàn)見 src/client.ts它聲明了與服務(wù)端相同的插件id: i18n并通過$InferServerPlugin完成類型關(guān)聯(lián)。注意客戶端不承擔(dān)翻譯邏輯——錯(cuò)誤消息已經(jīng)由服務(wù)端按檢測(cè)到的語言翻譯完畢客戶端插件只負(fù)責(zé)類型層面的銜接。八、驗(yàn)證與測(cè)試倉(cāng)庫(kù)為插件提供了覆蓋全面的單元測(cè)試 i18n.test.ts共覆蓋八個(gè)維度基于Accept-Language頭的檢測(cè)法語、德語、質(zhì)量值排序、fr-CA基礎(chǔ)碼裁剪、不可用語言回退基于 Cookie 的檢測(cè)及其與 header 的優(yōu)先級(jí)翻譯缺失時(shí)的兜底行為getLocale回調(diào)檢測(cè)及無請(qǐng)求場(chǎng)景非錯(cuò)誤響應(yīng)不被改動(dòng)defaultLocale的三種解析分支與空翻譯集合報(bào)錯(cuò)內(nèi)置語言的完整性22 個(gè)語言全部導(dǎo)出、10 個(gè)關(guān)鍵錯(cuò)誤碼非空。你可以在倉(cāng)庫(kù)根目錄運(yùn)行對(duì)應(yīng)包測(cè)試來驗(yàn)證當(dāng)前行為pnpm --filter better-auth/i18n test總結(jié)better-auth/i18n用極低的接入成本一個(gè)插件、一個(gè)translations配置為 Better Auth 的認(rèn)證錯(cuò)誤消息提供了完整的國(guó)際化能力22 種內(nèi)置語言開箱即用header/cookie/session/callback四種檢測(cè)策略覆蓋從瀏覽器自動(dòng)匹配到用戶手動(dòng)選擇、跨設(shè)備同步的全部場(chǎng)景defaultLocale與翻譯缺失保持原文的雙重兜底機(jī)制保證了任何情況下接口都不會(huì)出現(xiàn)空消息。若需深度定制TranslationDictionary類型會(huì)隨插件注冊(cè)表自動(dòng)聚合錯(cuò)誤碼配合getLocale回調(diào)你可以將任何自定義語言檢測(cè)邏輯無縫接入認(rèn)證流程。【免費(fèi)下載鏈接】better-authThe most comprehensive authentication framework項(xiàng)目地址: https://gitcode.com/GitHub_Trending/be/better-auth創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考