自动识别访客的浏览器语言与 GeoLite2 IP 归属地,在页面顶部显示可关闭的横幅,支持一键切换站点语言和货币。适用于多语言、多货币站点。
功能特性
- 浏览器语言识别 — 解析
Accept-Language请求头(支持 q 值排序与 BCP-47 渐进降级,如zh-Hant-TW → zh-hk,iOS 繁体标签不再误匹配英文)。 - 区域感知货币推荐 — 从语言标签提取地区子标签推荐对应货币:
zh-TW→ 新台币(TWD)、zh-HK→ 港币(未启用时降级)、简体zh→ 人民币;IP 归属地优先,本地开发(内网 IP 无归属地)自动按浏览器语言推荐。 - IP 归属地识别 — 复用系统内置的 GeoLite2 服务(
GeoLocationService),无需额外安装 MaxMind 组件,查询结果按 IP 缓存 24 小时。 - 横幅跟随访客语言 — 内置 20 种语言的横幅文案包;检测到中文访客时横幅直接显示中文(含繁体),阿拉伯语等 RTL 语言自动镜像布局,未覆盖的语言优雅回退到当前页面语言。
- 顶部横幅 — 固定显示在所有前台页面顶部,主色调可配置,响应式适配移动端,兼容默认主题及任何暴露
front.layout.app.head.bottom钩子的主题。 - 一键切换 — 单次请求同时切换语言和货币,访客停留在当前页面(自动改写 URL 语言前缀),仅允许同源地址重定向,安全可靠。
- 细分选择 — 可选"仅切换语言" / "仅切换货币"按钮。
- 智能默认映射 — 内置国家→货币(CNY、USD、EUR、JPY……)与国家→语言映射,均可通过后台 JSON 配置覆盖。
- 英语美元兜底 — 访客的语言/货币在后台都未启用时(如波兰语、泰铢),回退推荐英语 + 美元;兜底项未启用或已是当前值时自动跳过,不会出现无效横幅。
- 横幅自主选择器 — 横幅内含语言/货币下拉框(列出后台全部已启用项)+「确定」按钮:推荐不合心意时访客可自行挑选任意组合;兜底场景下也会弹出横幅供用户自选。
- 只弹有效横幅 — 访客语言与货币已与站点完全一致时不弹横幅,不打扰。
- 不反复打扰 — 访客完成切换(或关闭横幅)后不再提示;关闭状态按可配置天数记忆(localStorage)。
安装
- 将
LocaleDetector目录复制到plugins/下。 - 在后台插件管理中启用插件并打开配置。
- (可选但推荐)在 系统设置 → 工具(GeoLite2) 中下载数据库,IP 识别才能生效;未下载数据库时自动退化为仅按浏览器语言推荐。
后台配置
| 配置项 | 说明 |
|---|---|
| 启用识别横幅 | 总开关。 |
| 识别方式 | 浏览器语言优先 / IP 归属地优先 / 仅浏览器语言 / 仅 IP 归属地。 |
| 访客真实 IP 来源(CDN) | 存放访客真实 IP 的请求头:自动 / CF-Connecting-IP / X-Real-IP / X-Forwarded-For(第一个或最后一个)/ 服务器直连 IP / 禁用。 |
| 关闭后记住天数 | 关闭横幅后多少天内不再提示(0 = 永久)。 |
| 横幅主色调 | 任意 CSS 颜色,默认 #2b7fff。 |
| 仅首页显示横幅 | 开启后横幅只在首页展示。 |
| 国家→货币映射覆盖(JSON) | 例如 {"CN":"USD","DE":"USD"},与内置映射合并且优先。 |
| 语言→货币映射覆盖(JSON) | 例如 {"en":"EUR"},IP 归属地无法识别时按浏览器语言推荐货币。 |
只会推荐后台已启用的语言和货币,且仅在与访客当前设置不同时才显示横幅。
CDN 场景说明
插件原生适配 CDN:
- 页面缓存保持通用:页面 HTML 中只包含一小段静态加载器(CSS + JS),个性化推荐通过运行时请求
/locale-detector/suggest获取,该接口响应带Cache-Control: no-store, private——CDN 可放心缓存整页 HTML,不会把 A 访客的推荐结果泄露给 B 访客。 - 真实访客 IP:若 GeoLite2 识别出的是 CDN 节点国家而非访客国家,请把"访客真实 IP 来源(CDN)"改选为你的 CDN 实际设置的头(Cloudflare 选
CF-Connecting-IP,阿里云选X-Real-IP,或X-Forwarded-For的最后一个 IP)。自动模式优先取 CDN 头,且对X-Forwarded-For读取最后一个(由代理追加的)IP,可抵抗客户端伪造。 - 横幅不会使任何 HTML 缓存失效;每个页面浏览只有一次轻量 JSON 请求(访客关闭横幅或设置已匹配后完全跳过)。
工作原理
- 每个前台页面通过
front.layout.app.head.bottomBlade 钩子嵌入一小段静态加载器(仅 CSS + JS,可安全缓存)。 - 若访客未关闭过横幅,加载器请求
/locale-detector/suggest(no-store JSON),服务端根据浏览器语言与(可选的)IP 归属地计算推荐项。 - 若存在更合适的语言/货币,加载器渲染顶部横幅,并用当前页面地址生成切换链接。
- 点击"一键切换"访问
/locale-detector/switch?locale=...¤cy=...&redirect=...,控制器校验语言与货币合法性、写入会话,并重定向回当前页面(自动改写 URL 中的语言前缀)。