DEV Community

Cover image for Explaining the new internationalization features in Safari 15.4
Alan Dávalos
Alan Dávalos

Posted on • Edited on

Explaining the new internationalization features in Safari 15.4

Safari 15.4 released recently and among many things it includes a few new internationalization features. And while the blog post does explain which ones they are, it doesn't really mention what they do. So, I'll give you a brief summary for all of them.

Intl.Locale

calendars/collations/hourCycles/numberingSystems/timeZones

All of these properties will return an array of the things the locale supports. Here are some examples of what each one will return so that you can get an idea of what they're used for.

// calendars for Japanese (Japan) will return the Gregorian calendar and the Japanese calendar
new Intl.Locale('ja-JP').calendars; // ['gregory', 'japanese']

// collations A.K.A. ordering rules for Spanish (Mexico) will return traditional style ordering, European ordering rules, and emoji
new Intl.Locale('es-MX').collations; // ['trad', 'emoji', 'eor']

// hourCycles for Traditional Chinese (China) will be a 23 hour cycle
new Intl.Locale('zh-Hant-CN').hourCycles; // ['h23']
// but for English (USA) it will be a 12 hour cycle
new Intl.Locale('en-US').hourCycles; // ['h12']

// numberingSystems for Arabic (Bahrain) will return Arabic-Indic digits
new Intl.Locale('ar-BH').numberingSystems; // ['arab']
// but for Portuguese (Brazil) it will return Latin digits
new Intl.Locale('pr-BR').numberingSystems; // ['latn']

// timeZones for English (New Zealand) will return Auckland and Chatham
new Intl.Locale('en-NZ').timeZones; // ['Pacific/Auckland', 'Pacific/Chatham']
Enter fullscreen mode Exit fullscreen mode

Previous versions of the spec supported the non-plural versions of each of these properties. However, they will be undefined unless they are set through the options parameter of the Locale constructor.

// not setting with options
new Intl.Locale('ja-JP').calendar; // undefined
new Intl.Locale('ja-JP').calendars; // ['gregory', 'japanese']

// setting with options
new Intl.Locale('ja-JP', {calendar: 'gregory'}).calendar; // 'gregory'
new Intl.Locale('ja-JP', {calendar: 'gregory'}).calendars; // ['gregory'] as the 'japanese' one will get removed due to the options

// you can also set other calendars not there by default on the locale so be careful
new Intl.Locale('ja-JP', {calendar: 'buddhist'}).calendar; // 'buddhist'
new Intl.Locale('ja-JP', {calendar: 'buddhist'}).calendars; // ['buddhist']
Enter fullscreen mode Exit fullscreen mode

textInfo

The textInfo property currently contains an object with a single direction property which serves to indicate whether the locale's text is written right-to-left or left-to-right.

// Arabic
new Intl.Locale("ar").textInfo; // { direction: 'rtl'}
// Spanish
new Intl.Locale("es").textInfo; // { direction: 'ltr'}
Enter fullscreen mode Exit fullscreen mode

weekInfo

The weekInfo currently contains an object with various information regarding how weeks work on that region. It's especially useful when creating calendar UIs.

// week info for the UK
const gb = new Intl.Locale("en-GB").weekInfo;
gb.firstDay; // 1 - week starts on Monday
gb.weekend; // [6, 7] - weekend is Saturday and Sunday
gb.minimalDays; // 4 - for a week to be shown as the first week of a month it needs to be at least 4 days long

// week info for Algeria
const dz = new Intl.Locale("ar-DZ").weekInfo;
dz.firstDay; // 6 - week starts on Saturday
dz.weekend; // [5, 6] - weekend is Friday and Saturday
dz.minimalDays; // 1 - for a week to be shown as the first week of a month it needs to be at least 1 days long
Enter fullscreen mode Exit fullscreen mode

Browser Support

MDN

All the above features are supported in the following browsers:

  • Safari: 15.4 - supported
  • Chrome/Edge: 92* - supported (MDN says only with a flag but it worked in Edge 99 with no flags)
  • Firefox: 99 - not supported

Intl.DisplayNames

type: 'calendar'

This type option will allow you to get the localized name for any of the supported calendar types.

new Intl.DisplayNames(['en'], { type: 'calendar' }).of('gregory'); // 'Gregorian Calendar'
new Intl.DisplayNames(['en'], { type: 'calendar' }).of('japanese'); // 'Japanese Calendar'
Enter fullscreen mode Exit fullscreen mode

type: 'dateTimeField'

With this type option you can get localized strings for many different common words related to dates and time. Some examples include:

new Intl.DisplayNames(['en'], { type: 'dateTimeField' }).of('year'); // 'year'
new Intl.DisplayNames(['en'], { type: 'dateTimeField' }).of('minute'); // 'minute'                                               
new Intl.DisplayNames(['en'], { type: 'dateTimeField' }).of('weekday') // 'day of the week'
Enter fullscreen mode Exit fullscreen mode

languageDisplay option

The languageDisplay option is an option that can only be used for type: 'language' that determines the format for the string representing the language. It can be either 'dialect' or 'standard'.

new Intl.DisplayNames(['en'], { type: 'language', languageDisplay: 'dialect' }).of('en-AU'); // Australian English
new Intl.DisplayNames(['en'], { type: 'language', languageDisplay: 'standard' }).of('en-AU'); // English (Australia)
Enter fullscreen mode Exit fullscreen mode

Browser Support

No MDN data for these features specifically, but I tested them in the following browsers:

  • Safari: 15.4 - supported
  • Chrome/Edge: 99 - supported
  • Firefox: 99 developer edition - supported

Intl.DateTimeFormat

New timeZoneName types

Four new types of timeZoneName were added: 'shortOffset', 'longOffset', 'shortGeneric', and 'longGeneric'.

const date = new Date(Date.UTC(2020, 11, 20, 3, 23, 16, 738));

new Intl.DateTimeFormat('en', { timeZone: 'JST', timeZoneName: 'shortOffset'}).format(date); // '12/20/2020, GMT+9'
new Intl.DateTimeFormat('en', { timeZone: 'JST', timeZoneName: 'longOffset'}).format(date); // '12/20/2020, GMT+09:00'
new Intl.DateTimeFormat('en', { timeZone: 'JST', timeZoneName: 'shortGeneric'}).format(date); // '12/20/2020, Japan Time'
new Intl.DateTimeFormat('en', { timeZone: 'JST', timeZoneName: 'longGeneric'}).format(date); // '12/20/2020, Japan Standard Time'
Enter fullscreen mode Exit fullscreen mode

Browser Support

MDN

  • Safari: 15.4 - supported
  • Chrome/Edge: 99* - supported (MDN doesn't list this as supported but it worked in my tests. It might work in earlier versions. MDN issue)
  • Firefox: 91 - supported

Intl.NumberFormat / Intl.PluralRules

Safari 15.4's release notes mention that it added support for formatRange() and formatRangeToParts() in NumberFormat and for selectRange() in PluralRules. However, as the time of writing, those functions don't seem to be actually implemented in Safari 15.4 (Mac OS 10.15) nor have they been implemented in other browsers.

new Intl.NumberFormat('de-DE').formatRange; // undefined
new Intl.NumberFormat('de-DE').formatRangeToParts; // undefined

new Intl.PluralRules('de-DE').selectRange; // undefined
Enter fullscreen mode Exit fullscreen mode

Conclusion

Hopefully this article helped you understand better what all these new features were about and whether you can actually begin using them.

Credits

Cover photo by Nareeta Martin on Unsplash.

Top comments (1)

Collapse
 
offcorner profile image
OffCorner Developer

what to do with old versions of Safari? Currently these throw an error when using the "shortOffset" timeZoneName…