HTML 语言代码参考¶
HTML 的 lang 属性使用 BCP 47 语言标签，帮助读屏、断词、字体、翻译和搜索处理。
标签应描述内容的自然语言，不用于表示国家、字符编码或用户所在地。
基本写法¶
语言标签通常由语言、可选文字系统、可选地区和其他子标签组成。
| 组成 | 示例 | 含义 |
|---|---|---|
| 语言 | zh、en、fr |
ISO 639 语言子标签 |
| 文字系统 | Hans、Hant、Latn |
ISO 15924 script 子标签 |
| 地区 | CN、TW、US |
ISO 3166-1 或 UN M49 地区子标签 |
| 变体 | fonipa |
已注册的语言变体 |
| 私用 | x-example |
仅限约定范围，不具备通用语义 |
大小写不影响匹配，但惯例是语言小写、文字系统首字母大写、地区大写。
常用中文标签¶
| 标签 | 建议含义 | 备注 |
|---|---|---|
zh |
中文，地区或字形不重要 | 最宽泛 |
zh-CN |
中国大陆地区中文 | 常见简体中文页面 |
zh-SG |
新加坡地区中文 | 地区用语可能不同 |
zh-TW |
中国台湾地区中文 | 常见繁体中文页面 |
zh-HK |
中国香港地区中文 | 常见繁体中文页面 |
zh-Hans |
使用简体字形的中文 | 明确文字系统 |
zh-Hant |
使用繁体字形的中文 | 明确文字系统 |
zh-Hans-CN |
简体字形、中国大陆地区 | 只有确有区分需要时使用 |
zh-Hant-HK |
繁体字形、中国香港地区 | 只有确有区分需要时使用 |
不要使用过时或非标准写法如 zh_CN；BCP 47 子标签使用连字符，不用下划线。
常用语言标签¶
| 标签 | 语言或地区变体 |
|---|---|
en |
英语 |
en-US |
美国英语 |
en-GB |
英国英语 |
ja |
日语 |
ko |
韩语 |
fr / fr-CA |
法语 / 加拿大法语 |
de |
德语 |
es / es-MX |
西班牙语 / 墨西哥西班牙语 |
pt-BR / pt-PT |
巴西葡萄牙语 / 葡萄牙葡萄牙语 |
ru |
俄语 |
ar |
阿拉伯语 |
hi |
印地语 |
只在拼写、发音、日期格式或本地化内容确实不同时增加地区子标签。
文档内语言切换¶
| 场景 | 做法 |
|---|---|
| 整页主要语言 | 在根元素 <html> 设置 lang |
| 一段引用为其他语言 | 在最近的容器设置 lang |
| 专有名词发音需切换 | 在对应 span 等元素设置 lang |
| 用户生成内容语言未知 | 不要随意猜测；可在可靠检测后标注 |
| 无自然语言内容 | 必要时使用空值 lang="" 取消继承 |
lang 会继承给后代，因此无需在每个元素重复声明。
XML 序列化文档还可能需要 xml:lang；普通 text/html 以 lang 为主。
不要混淆¶
| 属性或头 | 作用 | 与 lang 的区别 |
|---|---|---|
charset=utf-8 |
字节到 Unicode 的解码 | 不是自然语言 |
hreflang |
链接目标的语言提示 | 不改变当前元素内容语言 |
Content-Language |
HTTP 元数据提示 | 不能替代准确的元素 lang |
dir="rtl" |
文字方向 | 语言与方向应分别表达 |
Accept-Language |
客户端语言偏好 | 不是可靠身份或地理位置证明 |
阿拉伯语、希伯来语等常需 dir="rtl"；混合方向文本可考虑 dir="auto"。
本地化与服务端¶
- 使用
Accept-Language作为偏好提示，并允许用户明确选择和持久化语言。 - 响应因语言变化时，缓存应正确区分变体，例如谨慎使用
Vary: Accept-Language。 - 不根据语言偏好推断权限、国籍、时区、货币或法律资格。
- URL 语言前缀、翻译链接和 canonical/hreflang 策略应保持一致。
- 日期、数字和货币格式使用国际化 API，不只替换界面文字。
检查要点¶
- 根元素是否存在准确的
lang？ - 页面内明显的语言切换是否在最近元素标注？
- 标签是否使用连字符并避免不必要的地区细分？
- 读屏发音、断词和双向文本是否经过实际测试？