The Locale Concept

Slide navigation: Forward with space bar, →, or PgDn. Backwards with ← or PgUp.

Locales

• A locale specifies the language, location, and preferences for formatting information of users of your software.
• Examples:
  • German users in Switzerland.
  • Thai users who prefer Thai numerals.
• Number formatting depends on the locale:

  123,456.78 (United States)
  123.456,78 (Switzerland)
  ๑๒๓,๔๕๖.๗๘ (Thailand with Thai numerals)
  

• With dates, the differences are more pronounced:

  March 22, 1961
  22. März 1961
  1961年3月22日
  

Specifying a Locale

• JavaScript supports BCP 47 language tags.
• A language tag consists of up to five components:
  1. A language, specified by two or three lowercase letters, such as de or zh.
  2. Optionally, a script, specified by four letters with initial caps, such as Latn, Cyrl, Hant.
  3. Optionally, a country or region, with two uppercase letters or three digits, such as US or CH.
  4. Optionally, a variant (rare).
  5. Optionally, an extension such as u-nu-thai.
• Desired locale can be a single language tag or an array in decreasing priority: ['de-CH', 'fr-CH', 'en']

Demo

Options

• Most locale-specific functions have additional options that can be provided in an object, such as { sensitivity: 'case' }
• All locale-specific functions support the localeMatcher option:
  • 'lookup' uses the algorithm in http://tools.ietf.org/html/rfc4647#section-3.4.
  • 'best fit' allows the runtime to choose a locale.
• Call resolvedOptions on internationalization objects to obtain all computed options:

  const collator = new Intl.Collator('en-US-u-kf-lower', { sensitivity: 'base' })
  collator.resolvedOptions() → {
    locale: 'en',
    usage: 'sort',
    sensitivity: 'base',
    ignorePunctuation: false,
    numeric: false,
    caseFirst: 'lower',
    collation: 'default'
  }
  

What's Missing?

• Locale discovery
  • No mechanisms for finding user locale, all known locales, localized locale names.
  • Intl.getCanonicalLocales only normalizes provided locale names.
  • Intl.Xxx.supportedLocalesOf only filter provided locale names.
• MessageFormat
  • Word order
  • Singular/plural/small quantities
  • Gender
• Resource bundles
  • String translations
  • Fallback

Localizing Numbers and Strings

Number Formatting

• new Intl.NumberFormat('de').format(123456.78) →  '123,456.78'

• The formatToParts method yields an array of the parts:

  [ { type: 'integer', value: '123' },
    { type: 'group', value: ',' },
    { type: 'integer', value: '456' },
    { type: 'decimal', value: '.' },
    { type: 'fraction', value: '78' } ]
  

• Language tag extensions:
  • nu (numbering): latn, arab, thai, ...
• Options:
  • style: decimal (default), currency, percent
  • currency: ISO 4217 currency code such as USD or EUR. Required for currency style.
  • useGrouping: true (default) to use grouping separators.
  • minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits

Collators

• const words = ['Alpha', 'Zulu', 'able', 'zebra', 'Ångström']
  words.sort(new Intl.Collator('en').compare) → [ 'able', 'Alpha', 'Ångström', 'zebra', 'Zulu']
  words.sort(new Intl.Collator('sv').compare) → [ 'able', 'Alpha', 'zebra', 'Zulu', 'Ångström']
  

• Language tag extensions:
  • co (collation): phonebook, phonetic, reformed, pinyin, ...
  • kn (numeric collation): true ('1' < '2' < '10'), false (default)
  • kf (case first): upper, lower, false (default)
• Options:
  • usage: sort (default), search
  • sensitivity: base (a = A = Å), accent (a = A ≠ Å), case (a ≠ A = Å), variant (a, A, Å all different)
  • ignorePunctuation: true, false (default)
  • numeric, caseFirst: See kn, kf above.
• More examples:

  ['Österreich', 'Offenbach'].sort(new Intl.Collator('de-u-co-phonebk').compare)
    // In German phonebooks (but not dictionaries), Ö is considered as Oe
  ['part1', 'part10', 'part2', 'part9'].sort(new Intl.Collator('en-u-kn-true').compare)
    → ["part1", "part2", "part9", "part10"]
  

Localized String Methods

• String toLocaleUpperCase, toLocaleLowerCase

  'Großhändler'.toLocaleUpperCase('de') → 'GROSSHÄNDLER'
  

• String localeCompare

  'part10'.localeCompare('part2', 'en', { numeric: true }) → 1
  

• String normalize combines/decomposes accents, ligatures:

  ['NFC', 'NFD', 'NFKC', 'NFKD'].map(mode => [...'Å™'.normalize(mode)])
    → ['Å', '™'], ['A', '°', '™'], ['Å', 'T', 'M'], ['A', '°', 'T', 'M']

Plural Rules

• Some languages have special forms for small quantities.
• English: 0 dollars, 1 dollar, 2, 3, 4, 5, ... dollars.
• Russian: 0 рублей, 1 рубль, 2, 3, 4 рубля, 5, ... рублей

• [0, 1, 2, 3, 4, 5].map(i => (new Intl.PluralRules('en').select(i)))
    → ['other', 'one', 'other', 'other', 'other', 'other']
  [0, 1, 2, 3, 4, 5].map(i => (new Intl.PluralRules('ru').select(i)))
    → ['many', 'one', 'few', 'few', 'few', 'many']
  

• The PluralRules class just produces the English form names. They still need to be mapped to the localized word forms.
• Options:
  • type: cardinal (default), ordinal
• English ordinal: 0th, 1st, 2nd, 3rd, 4th, 5th

  const rules = new Intl.PluralRules('en', { type: 'ordinal' })
  [0, 1, 2, 3, 4, 5].map(i => (rules.select(i)))
    → ['other', 'one', 'two', 'few', 'other', 'other']

Lists

• const list = ['Goethe', 'Schiller', 'Lessing']
  new Intl.ListFormat('en', { type: 'conjunction' }).format(list)
    → 'Goethe, Schiller, and Lessing'
  new Intl.ListFormat('de', { type: 'disjunction' }).format(list)
    → 'Goethe, Schiller oder Lessing' 
  

• Options:
  • type: conjunction (default), disjunction, unit
  • style: long, short, narrow (with unit type only)
• The unit type is for unit lists like “7 pounds 11 ounces”, but it produces commas in long and short styles—Chicago and AP wouldn't approve

Localizing Dates

Date and Time

• const newYearsEve = new Date(1999, 11, 31)
  new Intl.DateTimeFormat('en').format(newYearsEve) → 12/31/1999 
  new Intl.DateTimeFormat('de').format(newYearsEve) → 31.12.1999
  new Intl.DateTimeFormat('en', {
    year: 'numeric',
    month: 'short',
    day: 'numeric',
  }).format(new Date()) → Dec 31, 1999
  

• Language tag extensions:
  • nu (numbering): latn, arab, thai, ...
  • ca (calendar): gregory, hebrew, buddhist, ...
  • hc (hour cycle): h11, h12, h23, h24
• Options:
  • timeZone: UTC, Europe/Berlin, ... (default local time)
  • hour12: true, false
  • hourCycle: h11, h12, h23, h24
  • formatMatcher: basic, best fit (default)
  • month: 2-digit (09), numeric (9), narrow (S), short (Sep), long (September)
  • year, day, hour, minute, second: 2-digit, numeric
  • weekday, era: long, short, narrow
  • timeZoneName: short, long
  • dateStyle, timeStyle (Stage 3): full, long, medium, short

Relative Time

• new Intl.RelativeTimeFormat('en', { numeric: 'auto'}).format(-1, 'day') → 'yesterday'
  new Intl.RelativeTimeFormat('fr', { numeric: 'auto'}).format(-10, 'days') → 'il y a 10 jours'

• The format/formatToParts method has two arguments: a quantity and a unit:
  • year, quarter, month, week, day, hour, minute, second (or their plurals, such as years)
• Options:
  • numeric: always (1 day ago, default), auto (yesterday)
  • style: long, short, narrow

Localized Date Methods

• Date toLocaleString, toLocaleDateString, toLocaleTimeString take locale and options arguments.

  const newYearsEve = new Date(1999, 11, 31, 23, 59) 
  newYearsEve.toLocaleDateString('de') → '31.12.1999'
  newYearsEve.toLocaleTimeString('de') → '23:59:00'
  newYearsEve.toLocaleString('de') → '31.12.1999, 23:59:00'

• Can override toLocaleString in any class.

End of Lesson 11