返回知识中心
平台

navigator.languages 与应用本地化:从浏览器语言提示选择正确的 locale

navigator.languages 返回有序的浏览器语言提示。学习一套协商顺序:尊重用户的明确选择、保留完整回退,并且不用语言推断身份。

BotBrowser Team

文档中心

想直接进入 平台 文档吗?

这篇文章属于知识中心的指南库。若你要步骤化配置、参考说明和持续更新,请直接进入对应 docs 分区。

浏览器语言偏好可以帮助应用选择第一种翻译,但它只是提示。navigator.language 表示主要语言,navigator.languages 可能返回有序偏好列表。它们都不能证明用户住在哪里、属于哪个国家,或用户在每项任务中想用哪种语言。可靠的应用应协商受支持的 locale,提供语言选择器,并在资源缺失时保留可读的回退体验。

BotBrowser 配置可以设置浏览器语言和 locale,也可以使用从代理推导的 auto 值;但 BotBrowser 不会翻译应用内容,也不会替代应用内的明确语言选择。浏览器提示可以作为协商输入,翻译、同意和回退仍由应用负责。

TL;DR

navigator.language 和 navigator.languages 是本地化提示:它们帮助应用选择初始 locale,但不能可靠地证明身份或位置。应对照受支持的 locale 列表协商,让应用内的明确语言选择优先于浏览器提示,并始终提供完整的默认体验。

目录

Navigator 接口公开浏览器或用户设置的语言偏好。MDN Navigator.language 说明主要语言标签,WHATWG Navigator.languages 说明有序偏好列表。fr-CA 表示内容的语言和地区偏好,不表示用户的实际地理位置。

列表可能为空、只有一个值,也可能在浏览器设置改变后更新。应把它当作选择过程的输入,而不是永久画像。文档的 lang 属性承担不同职责:它帮助屏幕阅读器选择发音规则,并且在可见语言改变时必须同步更新。

协商受支持的 locale

先列出应用真正完成翻译的 locale。规范化语言标签,先尝试最具体的地区形式,再回退到父语言。若支持 fr-CA、fr 和 en,加拿大法语请求可使用 fr-CA,其他法语请求使用 fr,剩余请求使用 en。不要编造翻译,也不要把不同地区当成完全相同。

可以使用这样的顺序:已保存的明确选择、navigator.languages 中第一个受支持值、列表不可用时的 navigator.language,最后是稳定的产品默认语言。这一顺序也适用于只能提供较少信息的内嵌网页。默认语言必须是完整体验,不能显示未翻译的键名。

国际化要区分语言、文字和地区。W3C Internationalization 说明这些标签部分不能互相替代。缺少某个变体时,应说明采用了哪种回退,并让用户能在选择器中切换其他语言。

结构化匹配时,先用 Intl.Locale 解析并规范化标签,再与受支持的 locale 比较。服务器也可以使用 HTTP Accept-Language 请求头选择初始响应,但它只是偏好提示,不能证明身份或位置。只保留协商所需的最少信息,并让保存的明确应用选择优先于两者;BotBrowser 能设置浏览器语言输入,但不决定服务器策略或应用最终 locale。

让明确选择保持优先

自动选择适合首次访问,但不能让用户困在看不懂的界面。选择器应显示已翻译的语言名称,有明确的当前值,并支持键盘操作。只有在用户明确选择后才保存 locale;再次访问时,先恢复该选择,再读取已变化的浏览器偏好。说明选择影响当前页面、账户还是后续访问。

切换时保留内容、焦点、表单和草稿。如果资源加载失败,保留上一个可读语言并提供重试。语言偏好不是推广消息、数据传输或法律决定的同意。语言协商只改变呈现方式,不能改变功能的隐私政策。

加载资源而不破坏内容

对翻译资源做版本管理,并验证每个页面需要的键都存在。过渡期间显示原来的文字或上一版本,而不是内部键名。不要把独立短语拼接成句子,因为语序和复数规则会随语言变化。日期、数字和列表应使用 Intl 格式化;存储数据保持规范形式,不能用语言推断税务国家或支付方式。

更新文档 lang、标题、描述、alternate 链接和文字方向。测试长译文、从右到左文字、数字与代码混排、缩放和大字体。多语言 URL 应保持相同内容意图;缺少翻译时不能把有效 URL 重定向到无关首页。

测试偏好、fallback 与无障碍

测试空偏好列表、不支持的地区、带文字系统的标签,以及只提供 navigator.language 的浏览器。先做明确选择,再改变浏览器偏好,确认应用选择仍然优先;清除应用选择后,确认协商再次可预测。

测试慢网、请求中断和过期缓存。保留用户输入,提供进度说明和可恢复的重试。用键盘操作选择器,验证语言切换后的焦点,并让屏幕阅读器读到新的 lang 和标签。检查复数、十进制分隔符、文本扩展和放大显示。

用一份固定的验收 fixture,让规则变化可以被复现,而不依赖测试者本人的浏览器设置。把受支持列表设为 en、fr 和 fr-CA,然后由 fixture 提供浏览器偏好与已保存的选择,逐行运行。记录选中的 locale、它的决策来源、加载的文案包版本和渲染后的文档 lang。预期结果在服务器响应和水合之后应当一致;即使页面最终停在一个可读的语言上,只要不一致就算失败。

fixture 输入预期选择验收检查
已保存账户 fr-CA;浏览器 en来自账户的 fr-CA改动浏览器输入不会替换账户的选择
无已保存选择;浏览器 fr-BE,enfr 回退到父语言选择器写明该回退;文档 lang 为 fr
无已保存选择;浏览器 deen 默认完整英文文案包加载,不出现原始键名
设备选择 en;账户 fr登录期间为 fr退出登录回到设备范围内的 en
fr-CA 文案包不可用完整的 fr 或 en关键控件无混排;重试仍然可用

隐私与边界

语言偏好与其他值组合时,可能增加浏览器配置的可识别性。如果应用只需要一个 locale,就不要把完整列表发送到分析系统。不能据此推断居住地、国籍或敏感属性。如果提供远程翻译,要说明接收文本的服务、保留期限以及启动传输的明确操作。缺少本地资源时,绝不能静默上传私密内容。关于浏览器侧的网页翻译,可参阅在 BotBrowser 中使用 Google Translate 翻译网页。

公开说明哪些 locale 完整、哪些使用语言回退,并始终保留可访问的默认路径。存储、同步或资源打包发生变化时重新检查控制边界。

日期和数字的显示应把 locale 决策与存储数据分开,可参考 Intl 格式化指南。还可以阅读浏览器隐私选择来检查数据边界。

通知、生成文件和支持记录也应遵循相同边界:改变标签,不改变数据或权限。

说明每个选择器的作用范围,并在资源缺失时显示清晰的回退选项。

语言标签可能包含文字系统和地区,协商时应保留这些区别。

协商应保持确定性,以便支持人员复现结果,同时不必保存完整的浏览器列表。

即使选择的资源包尚未加载,登录和恢复流程也应保持可理解。

服务器渲染和客户端渲染都应让已保存的明确选择保持相同优先级。

本地化质量包括标题、标签、提示、替代文本和复数规则,而不只是翻译词语。

缺少某个 locale 时,应提供其他语言、默认语言或重新加载的选择。

隐私控制、内嵌网页行为或国际化数据改变后,应重新检查协商路径。

默认语言必须让用户完成任务,而不是等待新的资源下载。

切换语言不能删除已输入的数据或已经授予的权限。

错误消息同样需要翻译,或提供用户能理解的回退。

存储的日期和金额含义不能因为显示 locale 改变。

文字方向与文档 lang 都属于无障碍支持。

浏览器偏好不能替代用户对内容传输的明确决定。

浏览器偏好与受支持资源协商,用户的明确选择优先于回退。

让每种 locale 的选择都易于理解,并说明如何在移动设备和桌面设备返回默认语言。

相同建议适用于移动和桌面浏览器。

实践结论

把浏览器语言值当作既定协商顺序中的一个输入:已保存的明确选择优先,其次 navigator.languages,再次 navigator.language,最后是完整的默认体验。在所有受支持的 locale 中保持选择器、回退和任务状态可用,并在浏览器隐私控制或资源打包变化时重新测试。在产品文档中写明支持的 locale,让缺译可以被诊断为边界而不是缺陷。

断言与来源对应

BotBrowser 可配置浏览器语言和区域设置,也可使用根据代理推导的 auto 值;但它不会翻译应用,也不会替代用户明确选择的界面语言,因此仍应保留应用内语言控制和回退方案。

公开来源

#Navigator.language#本地化#国际化#无障碍

本文属于指南: Web 平台能力面:一致性复核地图

在 BotBrowser 里跑一遍同样的检查

加载 profile,让刚读到的这些信号在浏览器内部保持一致,并在正式上线前先在自己的机器上确认结果。