search

tc39 / proposal-intl-locale-info

An API to expose information of locale, such as week data ( first day of a week, weekend start, weekend end), hour cycle, measurement system, commonly used calendar, etc.
MIT License
56 stars 11 forks source link

readme

Intl Locale Info API

Draft Spec

https://tc39.github.io/proposal-intl-locale-info

Stage

Stage 3

Entrance Criteria for Stage 1 (Proposal)

Entrance Criteria for Stage 2 (Draft)

Entrance Criteria for Stage 3 (Candidate)

Champion

Designated reviewers

ECMAScript editors

Implementation Status

Scope

A proposal to expose Locale information, such as week data (first day in a week, weekend start day, weekend end day, minimum day in the first week), and text direction hour cycle used in the locale ~,measurement system used in the locale~.

Motivation / Use Case

Locale Information is necessary for many low level operations.

High Level Design

Add methods to Intl to get object to contains group of information:

Week Data

let he = new Intl.Locale("he")
he.getWeekInfo()
// {firstDay: 7, weekend: [5, 6], minimalDays: 1}
let af = new Intl.Locale("af")
af.getWeekInfo()
// {firstDay: 7, weekend: [6, 7], minimalDays: 1}
enGB = new Intl.Locale("en-GB")
enGB.getWeekInfo()
// {firstDay: 1, weekend: [6, 7], minimalDays: 4}

let msBN = new Intl.Locale("ms-BN")
msBN.getWeekInfo()
// {firstDay: 7, weekend: [5, 7], minimalDays: 1}  // Brunei weekend is Friday and Sunday but not Saturday

Monday is 1 and Sunday is 7, as defined by ISO-8861 and followed by Temporal proposal

Text Information

l = new Intl.Locale("ar")
let ti = l.getTextInfo();
// { direction: "rtl" }
ti.direction
// rtl

Defaults

~/v8/v8$ out/x64.release/d8 --harmony_intl_locale_info
V8 version 9.1.0 (candidate)
d8> ar = new Intl.Locale("ar")
ar
d8> ar.getCalendars()
["gregory", "coptic", "islamic", "islamic-civil", "islamic-tbla"]
d8> ar.getCollations()
["compat", "emoji", "eor"]
d8> ar.getHourCycles()
["h12"]
d8> ar.getNumberingSystems()
["latn"]
d8> ar.getTimeZones()
undefined

d8> arEG = new Intl.Locale("ar-EG")
ar-EG
d8> arEG.getCalendars()
["gregory", "coptic", "islamic", "islamic-civil", "islamic-tbla"]
d8> arEG.getCollations()
["compat", "emoji", "eor"]
d8> arEG.getHourCycles()
["h12"]
d8> arEG.getNumberingSystems()
["arab"]
d8> arEG.getTimeZones()
["Africa/Cairo"]

d8> arSA = new Intl.Locale("ar-SA")
ar-SA
d8> arSA.getCalendars()
["islamic-umalqura", "gregory", "islamic", "islamic-rgsa"]
d8> arSA.getCollations()
["compat", "emoji", "eor"]
d8> arSA.getHourCycles()
["h12"]
d8> arSA.getNumberingSystems()
["arab"]
d8> arSA.getTimeZones()
timeZones: ["Asia/Riyadh"]

d8> ja = new Intl.Locale("ja")
ja
d8> ja.getCalendars()
["gregory", "japanese"]
d8> ja.getCollations()
["unihan", "emoji", "eor"]
d8> ja.getHourCycles()
["h23"]
d8> ja.getNumberingSystems()
["latn"]
d8> ja.getTimeZones()
undefined

d8> jaJP = new Intl.Locale("ja-JP")
ja-JP
d8> jaJP.getCalendars()
["gregory", "japanese"]
d8> jaJP.getCollations()
["unihan", "emoji", "eor"]
d8> jaJP.getHourCycles()
["h23"]
d8> jaJP.getNumberingSystems()
["latn"]
d8> jaJP.getTimeZones()
["Asia/Tokyo"]}

d8> enUS = new Intl.Locale("en-US")
en-US
d8> enUS.getCalendars()
["gregory"]
d8> enUS.getCollations()
["emoji", "eor"]
d8> enUS.getHourCycles()
["h12"]
d8> enUS.getNumberingSystems()
["latn"]
d8> enUS.getTimeZones()
["America/Adak", "America/Anchorage", "America/Boise", "America/Chicago", "America/Denver", "America/Detroit", "America/Indiana/Knox", "America/Indiana/Marengo", "America/Indiana/Petersburg", "America/Indiana/Tell_City", "America/Indiana/Vevay", "America/Indiana/Vincennes", "America/Indiana/Winamac", "America/Indianapolis", "America/Juneau", "America/Kentucky/Monticello", "America/Los_Angeles", "America/Louisville", "America/Menominee", "America/Metlakatla", "America/New_York", "America/Nome", "America/North_Dakota/Beulah", "America/North_Dakota/Center", "America/North_Dakota/New_Salem", "America/Phoenix", "America/Sitka", "America/Yakutat", "Pacific/Honolulu"]

d8> enNZ = new Intl.Locale("en-NZ")
en-NZ
d8> enNZ.getCalendars()
["gregory"]
d8> enNZ.getCollations()
["emoji", "eor"]
d8> enNZ.getHourCycles()
["h12"]
d8> enNZ.getNumberingSystems()
["latn"]
d8> enNZ.getTimeZones()
["Pacific/Auckland", "Pacific/Chatham"]

d8> zh = new Intl.Locale("zh")
zh
d8> zh.getCalendars()
["gregory", "chinese"]
d8> zh.getCollations()
["pinyin", "big5han", "gb2312han", "stroke", "unihan", "zhuyin", "emoji", "eor"]
d8> zh.getHourCycles()
["h12"]
d8> zh.getNumberingSystems()
["latn"]
d8> zh.getTimeZones()
undefined

d8> zhTW = new Intl.Locale("zh-TW")      
zh-TW
d8>  zhTW.getCalendars()
["gregory", "roc", "chinese"]
d8>  zhTW.getCollations()
["stroke", "big5han", "gb2312han", "pinyin", "unihan", "zhuyin", "emoji", "eor"]
d8>  zhTW.getHourCycles()
["h12"]
d8>  zhTW.getNumberingSystems()
["latn"]
d8>  zhTW.getTimeZones()
["Asia/Taipei"]

d8> zhHK = new Intl.Locale("zh-HK")
zh-HK
d8> zhHK.getCalendars()
["gregory", "chinese"]
d8> zhHK.getCollations()
["stroke", "big5han", "gb2312han", "pinyin", "unihan", "zhuyin", "emoji", "eor"]
d8> zhHK.getHourCycles()
["h12"]
d8> zhHK.getNumberingSystems()
["latn"]
d8> zhHK.getTimeZones()
["Asia/Hong_Kong"]

d8> fa = new Intl.Locale("fa")
fa
d8> fa.getCalendars()
["persian", "gregory", "islamic", "islamic-civil", "islamic-tbla"]
d8> fa.getCollations()
["emoji", "eor"]
d8> fa.getHourCycles()
["h23"]
d8> fa.getNumberingSystems()
["arabext"]
d8> fa.getTimeZones()
undefined

~Unit Information~ DROPPED FEATURE

l = new Intl.Locale("ar")
let unitInfo = l.unitInfo;
// {measurementSystem: "metric"}
l.unitInfo.measurementSystem
// metric
l = new Intl.Locale("en-GB")
l.unitInfo
// {measurementSystem: "uksystem"}
l = new Intl.Locale("en-GB")
l.unitInfo
// {measurementSystem: "uksystem"}
l = new Intl.Locale("en")
l.unitInfo
// {measurementSystem: "ussystem"}

Polyfills

Polyfill Repo
@bart-krakowski/get-week-info-polyfill @bart-krakowski/get-week-info-polyfill