#Intl.DisplayNames S4

#提案：Intl.DisplayNames

#阶段

阶段 4

• 在 TC39 2020-09-21 会议中进入阶段 4。
• 在 TC39 2019-10-2 会议中进入阶段 3。
• 在 TC39 2019-6-5 会议中进入阶段 2。
• 在 TC39 2019-1-31 会议中进入阶段 1。
• 自 2017 年 7 月起在 ECMA402 成员中进行讨论。

对于额外的功能请求，请在新的 v2 仓库 中提出 issue。

#动机

Intl.DisplayNames 项目的主要动机是使开发人员能够在客户端获取语言、地区或文字显示名称的翻译。语言、地区或文字显示名称的翻译需要大量的数据在网络上传输，而这些数据在大多数浏览器中已经可用。这些显示名称翻译也为开发人员带来了相当大的数据大小开销。该 API 将使 Web 开发人员能够减小其 HTML 和/或 ECMAScript 代码的大小，而无需包含显示名称的人类可读形式，从而减少下载大小以降低延迟。此外，该 API 将降低 Web 开发人员的本地化成本。我们的目标是通过 Intl API 公开这些数据，用于例如语言、地区和文字选择器等。

#收益

• 减少应用程序的下载大小，从而改善延迟。
• 使用户易于构建国际化的语言、地区或文字选择 UI 组件（下拉菜单或其他类型）。
• 降低开发人员的翻译成本。
• 在 Web 上提供一致的语言、地区文字显示名称翻译。

#范围

本提案旨在提供特定与应用程序无关的项目的字符串翻译，而不是对所有类型的字符串进行翻译。我们在这里考虑两类字符串：

• 已经可用，因为其他 API 需要它们的字符串。例如，星期几的名称是提供 Intl.DateTimeFormat 功能所必需的。在没有直接 API 的情况下，我们看到程序解析 Intl.DateTimeFormat 的输出以查找这些名称，这是一种不可靠/不稳定的技术。
• 被普遍标准化且任何多语言 JavaScript 应用程序都可能需要的字符串。例如语言/地区名称。

例如，对于语言/地区名称，W3C 建议在处理多语言内容时使用语言选择器，而目前这意味着在每个此类网站上提供一长串翻译后的语言/地区名称。此类数据可能有时效性和政治敏感性，并且不太可能特定于任何特定网站（即，网站 A 不太可能想要与网站 B 不同的任何语言名称的翻译）。 因此，在引擎中提供这些数据可以降低发布带语言选择器的多语言网站的成本，并将维护 BCP47 语言/地区代码到显示名称的映射的责任移交给引擎，而引擎更有能力保持其更新。

包含的字符串集可能会随着时间的推移而增长，但我们期望根据务实的限制来限制增长，包括：

• 包含的字符串应在多种应用程序类型中具有普遍用途。
• 包含的字符串不应在数据大小方面给实现带来过多负担。
• 应该有实现可用于字符串值的开放数据源，例如 CLDR。
• 很少（从不）更改的字符串，因此不需要动态生成。
• 项目数量如此之少，以至于公开 Web API 并永远维护它比网站直接包含这些字符串更有负担的字符串集。

Intl.DisplayNames 中包含的其他字符串应通过未来的 ECMA-402 提案添加到规范中，并在 ECMA-402 工作组和 TC39 中作为 TC39 流程标准化的一部分进行展示。

#语法

要获取语言、文字或地区的本地化名称，请创建一个 Intl.DisplayNames 对象，并通过传入适当的标准代码来调用该方法。

Intl.DisplayNames 构造函数的参数遵循 ECMA402 标准中的其他 Intl 对象。第一个参数是 locales，它可以是 BCP 47 语言标签或此类语言标签的数组（更多信息）；第二个参数是一个选项对象。

Intl.DisplayNames( locales , options)
Intl.DisplayNames.prototype.of( code )

• options 需要具有 "type" 属性。
  • type 的值可以是 "region"、"script"、"language" 或 "currency"。
• options 可以有 "localeMatcher"、"style" 和 "fallback" 属性。
  • style 的值可以是 "narrow"、"short" 或 "long"，以指示显示名称的长度。例如，对于 type 为 "language"，of("en-US") 在 "long" 样式下将返回 "English (United States)"，但在 "short" 样式下返回 "English (US)"。默认值为 "long"。
• code 是一个字符串。
• Intl.DisplayNames.prototype.of( code ) 函数接受一个字符串作为输入并返回一个字符串，即 code 的显示名称。
  • 如果 type 为 "region"，则 code 应为 ISO-3166 两位字母地区代码 或 三位数字 UN M49 地理区域。
  • 如果 type 为 "script"，则 code 应为 ISO-15924 四位字母文字代码。
  • 如果 type 为 "language"，则 code 应为 UTS 35 的 Unicode 语言和区域设置标识符语法 中 unicode_language_id 语法的 languageCode ["-" scriptCode] ["-" regionCode ] *("-" variant ) 子序列。languageCode 可以是两位字母的 ISO 639-1 语言代码或三位字母的 ISO 639-2 语言代码。
  • 如果 type 为 "currency"，则 code 应为 3 字母 ISO 4217 货币代码。

#作者

• Frank Tang (@FrankYFTang)
• Zibi Braniecki (@zbraniecki)
• Sascha Brawer (@brawer)
• Nebojša Ćirić (@nciric)

#阶段 3 审阅者

• 审阅者
  • Daniel Ehrenberg (@littledan)
  • Bradley Farias (@mbeck)
• 编辑
  • Jordan Harband (@ljharb)
  • Kevin Smith (@zenparsing)

#先例

Mozilla 已经有 供应商特定的实现。

#用法

#地区代码显示名称

为区域设置创建 Intl.DisplayNames 并获取地区代码的显示名称。

// 获取英文的地区显示名称
var regionNames = new Intl.DisplayNames(['en'], {type: 'region'});
console.log(regionNames.of('419')); // "Latin America"
console.log(regionNames.of('BZ')); // "Belize"
console.log(regionNames.of('US')); // "United States"
console.log(regionNames.of('BA')); // "Bosnia & Herzegovina"
console.log(regionNames.of('MM')); // "Myanmar (Burma)"

// 获取繁体中文的地区显示名称
regionNames = new Intl.DisplayNames(['zh-Hant'], {type: 'region'});
console.log(regionNames.of('419')); // "拉丁美洲"
console.log(regionNames.of('BZ')); // "貝里斯"
console.log(regionNames.of('US')); // "美國"
console.log(regionNames.of('BA')); // "波士尼亞與赫塞哥維納"
console.log(regionNames.of('MM')); // "緬甸"

#语言显示名称

为区域设置创建 Intl.DisplayNames 并获取语言-文字-地区序列的显示名称。

// 获取英文的语言显示名称
var languageNames = new Intl.DisplayNames(['en'], {type: 'language'});
console.log(languageNames.of('fr')); // "French"
console.log(languageNames.of('de')); // "German"
console.log(languageNames.of('fr-CA')); // "Canadian French"
console.log(languageNames.of('zh-Hant')); // "Traditional Chinese"
console.log(languageNames.of('en-US')); // "American English"
console.log(languageNames.of('zh-TW')); // "Chinese (Taiwan)"]

// 获取繁体中文的语言显示名称
languageNames = new Intl.DisplayNames(['zh-Hant'], {type: 'language'});
console.log(languageNames.of('fr')); // "法文"
console.log(languageNames.of('zh')); // "中文"
console.log(languageNames.of('de')); // "德文"

#文字代码显示名称

为区域设置创建 Intl.DisplayNames 并获取文字代码的显示名称。

// 获取英文的文字显示名称
var scriptNames = new Intl.DisplayNames(['en'], {type: 'script'});
// 获取文字名称
console.log(scriptNames.of('Latn')); // "Latin"
console.log(scriptNames.of('Arab')); // "Arabic"
console.log(scriptNames.of('Kana')); // "Katakana"

// 获取繁体中文的文字显示名称
scriptNames = new Intl.DisplayNames(['zh-Hant'], {type: 'script'});
console.log(scriptNames.of('Latn')); // "拉丁文"
console.log(scriptNames.of('Arab')); // "阿拉伯文"
console.log(scriptNames.of('Kana')); // "片假名"

#货币代码显示名称

为区域设置创建 Intl.DisplayNames 并获取货币代码的显示名称。

// 获取英文的货币代码显示名称
var currencyNames = new Intl.DisplayNames(['en'], {type: 'currency'});
// 获取货币名称
console.log(currencyNames.of('USD')); // "US Dollar"
console.log(currencyNames.of('EUR')); // "Euro"
console.log(currencyNames.of('TWD')); // "New Taiwan Dollar"
console.log(currencyNames.of('CNY')); // "Chinese Yuan"

// 获取繁体中文的货币代码显示名称
currencyNames = new Intl.DisplayNames(['zh-Hant'], {type: 'currency'});
console.log(currencyNames.of('USD')); // "美元"
console.log(currencyNames.of('EUR')); // "歐元"
console.log(currencyNames.of('TWD')); // "新台幣"
console.log(currencyNames.of('CNY')); // "人民幣"

#支持材料：

• 用于 TC39 2019 年 1 月会议从阶段 0 提升到阶段 1 的幻灯片。
• 用于 TC39 2019 年 6 月会议从阶段 1 提升到阶段 2 的幻灯片。
• 用于 TC39 2019 年 10 月会议从阶段 2 提升到阶段 3 的幻灯片。
• 用于 TC39 2020 年 9 月会议从阶段 3 提升到阶段 4 的幻灯片。