Intl

web_APIs

Intl 是 ES 国际化 API 的一个命名空间，提供了精确的字符串对比，数字的格式化和日期时间格式化。

internationalization 构造器和其他语言相关的方法及构造器使用通用的模式来识别语言环境（locales），并决定实际使用哪种：都接受 locales 和 options 参数，并会对请求使用的语言环境和支持的语言环境通过 options.localeMatcher 属性来协商。

locales 参数

locales 参数决定某次操作的语言环境，JS 的视线会校验 locales 参数，计算出一个能理解且最接近的语言环境。例如：

• undefined：试用默认语言环境；
• A locale：一个 locale identifier（语言环境标识）或者一个包裹了一个 locale identifier 的 Intl.Locale 对象；
• A list of locales：任何其他值都会被转化成一个对象，然后当成一个 locales 数组来处理。

上述的后两种情况下，实际使用取决于 locale negotiation 且支持性最好的语言环境。

一个 locale 标识是一个字符串，有以下组成：

• BCP 47 语言标记
• （可选）脚本标记
• （可选）地区/国家标记
• （可选）一个或以上变体的标记（必须是独有的）
• （可选）一个或以上 BCP 47 扩展
• （可选）私有的扩展序列

每个标记和序列间使用 hyphens（-）隔开。Locale 标识是大小写敏感的。对于脚本标记习惯使用首字母大写的写法；对于地区标记使用全部大写；其他标记和序列使用小写：

• "hi"：印地语（语言标记）
• "de-AT"：德语-奥地利（地区标记）
• "zh-Hans-CN"：中文-简体（脚本标记）-中国

BCP 47 语言标记注册列表：IANA Language Subtag Registry

BCP 47 扩展使用一个数字/字母和一个或以上 2~8 位的字母/数字组成，每个数字或者字母只支持一个序列。目前只有两个语义化定义的扩展：

• "u"（Unicode）扩展用来请求 Intl API 对象额外的定义化，例如
  
  • "de-DE-u-co-phonebk"：使用德语的 phonebook（电话簿）顺序变体
  • "th-TH-u-nu-thai"：在数字格式化（nu）中使用泰语数字
  • "ja-JP-u-ca-japanese"：在日期格式化（ca）中使用日本的日历格式（例如2013 -> 平成25）
  • "en-GB-u-ca-islamic"：在日期格式化（ca）中使用伊斯兰格式（回历）

BCP 47 扩展标记：Unicode CLDR Project

• "t"（transformed）扩展表示转换后的内容，例如转成另一种语言的文本："de-t-en"

options 参数

options 参数必须是一个对象，其属性会根据构造函数或者方法变化，如果没有提供 options 参数，会使用所有属性的默认值。

options.localeMatcher 属性适用于所有语言敏感的构造器和函数，这个属性的值可以是 "lookup" 或 "best fit"，用来选择下面提到的本地语言匹配算法：

语言标识和协商

locales 参数指定的一组语言环境在 Unicode 扩展被移除后，被 interpreted（解释）为来自应用的 prioritized request（优先请求）。运行时将它和支持的语言环境比较，选出最佳的可用结果。

• "look up"：lookup 使用 BCP 47 的 Lookup 算法；
• "best fit"：在 lookup p让运行时提供至少一个或以上适用于请求的语言环境；

如果应用没有提供 locales 参数，或者运行时没有匹配到请求的语言，使用默认的运行时语言。

如果选中的语言标识具有 Unicode 扩展子序列，那么这个扩展会用来自定义化函数的构造器或行为。每个函数的构造器只支持一组扩展。例如 "co"（collation，校对）只有 Intl.Collator 支持，而且 "phonebk" 值只有德语支持。

构造器属性

Intl.Collator()

校对器对象的构造函数，支持语言敏感的字符串比较。

• Intl.Collator().compare 函数用来对指定语言环境的字符串进行排序比较。

const collator = new Intl.Collotor('zh')
const list = ['赵', '钱', '孙', '李']
list.sort() // ['孙', '李', '赵', '钱']
list.sort(collator.compare)  // ['李', '钱', '孙', '赵']

• Intl.Collator.resolvedOptions() 返回构造时用来初始化的选项

new Intl.Collator('zh').resolvedOptions()
/** 
{
    caseFirst: "false",
    collation: "default",
    ignorePunctuation: false,
    locale: 'zh',
    numeric: false,
    sensitivity: "variant",
    usage: "sort"
}
*/

Intl.DateTimeFormat()

支持语言敏感的时间日期格式化的对象构造器。

const date = new Date(Date.UTC(2020, 11, 20, 3, 23, 16, 738))
console.log(new Intl.DateTimeFormat('en-US').format(date))
// "12/20/2020"
console.log(new Intl.DateTimeFormat('zh-CN').format(date))
// "2020/12/20"
console.log(new Intl.DateTimeFormat('en-GB', { dateStyle: 'full', timeStyle: 'long', timeZone: 'Australia/Sydney' }).format(date))
// "Sunday, 20 December 2020 at 14:23:16 GMT+11"

• Intl.DateTimeFormat().format(Date)

将一个日期对象构造成对应语言环境的格式（使用 options）

• Intl.DateTimeFormat().resolvedOptions()

返回构造时初始化对象使用的选项

• Intl.DateTimeFormat().formatDateRange(Date, Date)

返回一个日期范围

const fromDate = new Date(Date.UTC(2020, 11, 20, 3, 23, 16, 738))
const toDate = new Date(Date.UTC(2023, 2, 27, 22, 33, 13, 633))
console.log(new Intl.DateTimeFormat().formatRange(fromDate, toDate))
// "2020/12/20 - 2023/3/28"

• 使用 options

const date = new Date(Date.UTC(2022, 11, 20, 3, 0, 0))
const options = {
    weekday: "long",
    year: "numeric",
    month: "long",
    day: "numeric"
}
console.log(new Intl.DateTimeFormat("de-DE", options).format(date))
// "Donnerstag, 20. Dezember 2012"
options.timeZone = "UTC"
options.timeZoneName = "short"
console.log(new Intl.DateTimeFormat("en-US", options).format(date))
// "Thursday, December 20, 2012, GMT"

• 获取 options

const options = { calendar: "chinese", numberingSystem: "arab" }
const dateFormat = new Intl.DateTimeFormat("default", options)
const usedOptions = dateFormat.resolvedOptions()
console.log(usedOptions.calendar)   // "chinese"
console.log(usedOptions.numberingSystem)    // "arab"
console.log(usedOptions.timeZone)
// "Asia/shanghai" (the users default time zone)

Intl.DisplayNames()

支持语言、地区和脚本展示名称的一致翻译的对象构造器

Intl.ListFormat()

支持语言敏感的列表格式化的对象构造器

• .format()

const list = ['Motorcycle', 'Bus', 'Car']
conosle.log(new Intl.ListFormat('en-GB', { style: 'long', type: 'conjunction' }).format(list))
// Motorcycle, Bus and Car
console.log(new Intl.ListFormat('zh-CN', { style: 'short', type: 'disjunction' }).format(list))
// Motorcycle、Bus或Car
console.log(new Intl.ListFormat('en-GB', { style: 'narrow', type: 'unit' }).format(list))
// Motorcycle Bus Car
console.log(new Intl.ListFormat('zh-CN', { style: 'narrow', type: 'unit' }).format(list))
// MotorcycleBusCar
// Motorcycle Bus Car

• .formatToParts()

const list = ['Motorcycle', 'Bus', 'Car']
console.log(new Intl.ListFormat('en-GB', { style: 'long', type: 'conjunction' }).formatToParts(list))
// [ { "type": "element", "value": "Motorcycle" },
//   { "type": "literal", "value: ", " },
//   { "type": "element", "value": "Bus" },
//   { "type": "literal", "value": ", and " },
//   { "type": "element", "value": "Car" } ]

Intl.Locale()

const locale = new Intl.Locale('en-CA')
console.log(locale.hourCycles)  // ['h12']
console.log(locale.timeZones)
/** 
/* [ "America/Blanc-Sablon",
/*   "America/Cambridge_Bay",
/*   "America/Coral_Harbour"
/*   ...,
/*   "America/Toronto",
/*   "America/YellowKnife" ]
*/
console.log(new Intl.Locale('zh-CN').timeZones)
/**
/* ["Asia/Shanghai", "Asia/Urumqi"]
*/

用来表示一个 Unicode 语言标识的对象构造器

Intl.NumberFormat()

支持语言敏感的数字格式化的对象构造器

options 文档

货币：

const number = 123456.789
console.log(new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' })).format(number)
// 123.456,79 €
console.log(new Intl.NumberFormat('en-IN', { maximumSignificantDigits: 3 })).format(number)
// 1,23,000

货币单位查询

单位：

console.log(new Intl.NumberFormat('en', { style: 'unit', unit: 'kilometer-per-hour' }).format(50))
// 50 km/h

Intl.PluralRules()

支持复数敏感且指定语言的复数语法的对象构造器；例如：1 => one; 6 => few; 20 => many

Intl.RelativeTimeFormat()

支持语言敏感的相对时间格式化的对象构造器。

const rtf1 = new Intl.RelativeTimeFormat('en', { style: 'narrow' })
console.log(rtf1.format(3, quarter))
// in 3 qtrs
console.log(rtf1.format(-1, 'day'))
// 1 day ago
const rtf2 = new Intl.RelativeTimeFormat('zh', { numeric: 'auto' })
console.log(rtf2.format(2, 'day'))
// 后天

Intl.Segmenter()

支持语言敏感的文本分段（text segmentation）对象的构造器；可以实现非空格分隔文本的词语分隔

静态方法

Intl.getCananicalLocales()

返回典范的（canonical）本地语言名称

Intl.supportedValuesOf()

返回实现了的特定日历，校对器，币种，数字系统

用例

格式化日期和数字

使用 Intl 来格式化日期和数字，转换成某个地区/语言的常用格式

const count = 26254.39
const date = new Date("2012-05-24")
const log = (locales) => {
    console.log(
        `${new Intl.DateTimeFormat(locale).format(date)} ${new Intl.NumberFormat(locale).format(count)}`
    )
}
log("en-US")    // 5/24/2012 26,254.39
log("de-DE")    // 24.5.2012 26.254,39