Web 平台 API / Intl · 浏览器内置的本地化引擎 / Intl.DisplayNames:把代码翻成人类可读的名字 待审核 4 / 9
DisplayNames · 代码→名称

Intl.DisplayNames:把代码翻成人类可读的名字

程序里到处是机器代码:locale 串 en-US、地区 HK、货币 JPY、书写体 Hant。要把它们显示成某个 locale 下的人类可读名称(「美式英语」「香港」「日元」),既不该自建翻译表,也不该硬编码。Intl.DisplayNames 就是这张「代码 → 名称」的本地化字典:new Intl.DisplayNames(locale, { type }) 造一个查询器,再 .of(code) 查名字。

它和 Intl.Locale 互补:Localeen-US 拆成字段(language='en'region='US'),DisplayNames 把这些代码翻成名字(language →「英语」、region →「美国」)。前者解析结构,后者负责展示。两者常配合:先 Locale 拆段,再对每段用 DisplayNames 取名。

1 · 主面板:of(code) 按 type 查名字

构造时必须指定 type——它决定 .of() 接收哪种代码。选 type、选 locale、点代码示例(或自己输),看查出来的名字。注意:of() 接收的是代码,不是名字,它只做单向的「代码 → 当前 locale 名称」。

图 1-1 · 按 type 查名字。可选 type 与 locale、点代码示例或自行输入,观察查得的名称。

六种 type,各收一类代码: language 收 BCP-47 语言串(en-US → 美国英语)、region 收 ISO 3166 地区码或 UN M49 三位数字码(JP → 日本、419 → 拉丁美洲;具体名称随 CLDR 版本变动,实测 HK 在 ICU 78.3 上是「中国香港特别行政区」、在 Chrome 151 上是「香港」,核对于 2026-08)、script 收 ISO 15924 书写体(Hant → 繁体)、currency 收 ISO 4217 货币码(JPY → 日元)、calendar 收历法标识(chinese → 农历)、dateTimeField 收日期字段名(month → 月)。style 给货币、语言等提供 long / short / narrow 几档长度,具体差异随 type 和 locale 而定。

2 · languageDisplay:「美式英语」还是「英语(美国)」

type:'language' 适用。dialect(默认)把带地区的语言串当成一个方言整体命名(en-US →「美国英语」);standard 则按语言 + 括注地区的形式拼(en-US →「英语(美国)」)。同一批代码,两种取值的对照:

图 2-1 · languageDisplay 在 dialect 与 standard 两档下的名称对照。

3 · fallback:查不到时给代码还是给 undefined

代码格式合法但当前 locale 没有对应名称时,行为由 fallback 决定:code(默认)原样回传传入的代码——注意 V8 未做规范要求的大小写归一,实测 of('hk') 原样返回 hkof('HK') 才查得到名称,所以代码得自己先规范化,noneundefined。渲染 UI 时若希望「查不到就别显示」,用 none 自行处理默认/回退,而不是把代码当名字显示出去。

图 3-1 · 查不到名称时 fallback 取 code 与 none 的差别。

fallback 只兜「合法但未知」的代码。 若代码连结构都不合法(地区给单个字母、货币给两位),of() 直接抛 RangeError,与 fallback 无关——上面输入框输个 region: Q 就能看到。所以传给 of() 的代码应先确保格式正确(必要时配合 Intl.Locale 规范化)。