Intl.DisplayNames 本地化名称转换教程

Intl.DisplayNames 是一个专为“反查”设计的现代国际化 API，能精准将标准代码（如"US"、"zh"、"USD"）按指定语言环境转换为本地化全称，远比 toLocaleString 更适合名称映射场景；它严格区分 region、language、currency 三类输入规范，对代码格式、大小写和语言标签高度敏感，用错类型或传入非标准值会静默返回 undefined，而真正挑战往往不在调用本身，而在于确保手头数据符合 ISO/BCP 47 等国际标准——掌握这些细节，才能让多语言应用的国家名、货币名、语言名真正准确、可靠、合规地呈现给全球用户。

Intl.DisplayNames 为什么比 toLocaleString 更适合查名称

因为 toLocaleString 只能格式化已有值（比如数字、日期），不能“反查”一个区域代码或货币符号对应的本地化全称。而 Intl.DisplayNames 是专为这种映射设计的 API，它不依赖真实数据实例，只靠类型和语言标签就能查出规范名称。

常见误用是拿它去格式化数字或日期——它做不到；也有人试图传入非标准字符串（如 "CN" 当作语言代码查国家名），结果返回 undefined，其实是没配对好 type 和输入值。

实操建议：

• type 必须与输入值严格匹配：查国家用 "region"，输 "US"；查语言用 "language"，输 "zh" 或 "zh-Hans"；查货币用 "currency"，输 "USD"
• 语言标签（locale）影响结果，但不是越长越好："zh-CN" 和 "zh" 对多数货币/区域返回一致，但对语言名可能不同（比如 "zh-Hant" 下 "en" 显示“英文”，"zh" 下可能显示“英语”）
• 浏览器兼容性需留意：Safari 14+、Chrome 90+、Firefox 87+ 支持完整功能；旧版 Safari 不支持 "currency" 类型

查国家/地区名：region 类型的典型用法

输入 ISO 3166-1 alpha-2 代码（如 "JP"、"BR"），输出对应语言下的国家全称。注意不是所有代码都有效——"ZZ" 或自定义短码会返回 undefined。

示例：

const regionNames = new Intl.DisplayNames(["zh-CN"], { type: "region" });
regionNames.of("JP"); // → "日本"
regionNames.of("US"); // → "美国"
regionNames.of("GB"); // → "英国"

容易踩的坑：

• 别把 "CN" 当成简体中文语言代码传进去——那是国家码，要用 type: "region" 才生效
• "UK" 不是标准区域码，正确写法是 "GB"；"HK" 是合法区域码，但某些 locale 下可能显示为“中国香港特别行政区”而非单纯“香港”
• 如果需要区分“台湾地区”这类表述，取决于目标 locale 的政治语境，API 本身不判断，只按 Unicode CLDR 数据返回

查货币全称：currency 类型的注意事项

type: "currency" 接收的是 ISO 4217 三字母代码（如 "CNY"、"EUR"），不是符号（"¥"）也不是小写缩写（"usd"）。大小写敏感，错一个字母就查不到。

示例：

const currencyNames = new Intl.DisplayNames(["ja-JP"], { type: "currency" });
currencyNames.of("CNY"); // → "中国元"
currencyNames.of("USD"); // → "米ドル"

关键细节：

• 不支持符号反查：传 "$" 或 "€" 会返回 undefined
• 部分货币在某些 locale 下有多个名称（如 "GBP" 在 "en-GB" 下是 "British Pound Sterling"，在 "en-US" 下是 "British Pound"），但 API 只返回一个主名称
• "XAU"（黄金）、"BTC"（比特币）等非法定货币代码，多数浏览器返回 undefined，因 CLDR 未收录

查语言名：language 类型的输入格式差异

type: "language" 支持多种输入格式：BCP 47 语言子标签（"en"、"pt-BR"）、Unicode 扩展（"en-u-hc-h12"），甚至私有使用子标签（"qaa"）。但最常用的是基础语言码或带脚本/地区的组合。

示例：

const langNames = new Intl.DisplayNames(["zh-Hans"], { type: "language" });
langNames.of("en");      // → "英语"
langNames.of("en-US");   // → "美国英语"
langNames.of("zh-Hant"); // → "繁体中文"

这里最容易忽略的一点：

• 输入 "zh" 和 "zh-CN" 在 type: "language" 下行为不同："zh" 查的是“中文”这个语言本身，"zh-CN" 查的是“中国大陆使用的中文变体”，后者可能返回“简体中文”或“中国大陆中文”，取决于 locale 和 CLDR 版本
• 像 "und"（未确定语言）这类特殊子标签，只有部分 locale 支持返回有意义的名称（如 "未知语言"），多数返回 undefined
• 如果你拿到的是用户 navigator.language（如 "en-US"），直接传给 of() 是安全的；但如果是后端传来的 "english" 这种自然语言字符串，得先映射成标准子标签才能用

真正麻烦的不是调用 API，而是确认你手里的字符串是否符合对应 type 的标准格式。区域码、货币码、语言子标签，每种都有自己的规范，混用就会静默失败。CLDR 数据更新慢，新加入的国家或加密货币符号短期内不会出现在 Intl.DisplayNames 结果里。

本篇关于《Intl.DisplayNames 本地化名称转换教程》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！