Typescript: Add Intl.Locale to es2020 lib

[boenrobot]

Search Terms

Locale, intl

Suggestion

Add Intl.Locale to the es2020 build target libs. It is supported in recent NodeJS versions, and recent Chrome versions, making it a suitable feature for inclusion.

Use Cases

Using the new Intl.Locale feature.

Examples

console.log((new Intl.Locale('en-US')).language); // Outputs "en"

Checklist

My suggestion meets these guidelines:

• [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
• [x] This wouldn't change the runtime behavior of existing JavaScript code
• [x] This could be implemented without emitting different JS based on the types of the expressions
• [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• [x] This feature would agree with the rest of TypeScript's Design Goals.

[RyanCavanaugh]

We'd prefer things be more broadly adopted (e.g. in Safari) before adding them to the built-in definitions.

[Dangoo]

Thanks @boenrobot for bringing this up!

This was added in Safari TP 107 (261215) as listed here on May 28th:
https://webkit.org/blog/10585/release-notes-for-safari-technology-preview-107/

Implemented Intl.Locale

[Dangoo]

Already have the types prepared. So just let me know when you are ready to accept a PR for that.

[boenrobot]

Cool!

About the types... I think it's a bit too restrictive and not future proof to require only the enumerated values in the option, especially since the standard isn't fixed... Maybe add "| string" as a possible option, so that IDEs can assist, but also have TS not complain if a different value is supplied? Keep (and maybe even export) the enumerations, so that if one wants to force the value to be among the enumerated, they can?

[Dangoo]

@boenrobot good catch!
I think this would do?

interface LocaleOptions {
    baseName?: string;
    calendar?: LDMLCalendarKey | string;
    caseFirst?: LDMLCollationCaseFirst | string;
    collation?: LDMLCollationKey | string;
    hourCycle?: LDMLHourCycleKey | string;
    language?: string;
    numberingSystem?: LDMLNumberingSystemKey | string;
    numeric?: boolean;
    region?: string;
    script?: ScriptCode | string;
}

Regarding the export this should already be the case since declared as namespace. So e.g. Intl.LDMLCalendarKey should already be available.

[longlho]

Couple of comments here:

• LMDLCalendarKey should just be a string. See https://ecma-international.org/ecma-402/7.0/index.html 10.1.3 Intl.Locale. There's no verification for calendar.
• LMDLCaseFirst should not be | string. Invalid value will trigger RangeError, see https://ecma-international.org/ecma-402/7.0/index.html#sec-Intl.Locale
• LDMLCollationKey should just be string.
• LDMLHourCycleKey should not be | string. Any value that's not h11, h12, h23, h24 will throw a RangeError. See https://ecma-international.org/ecma-402/7.0/index.html#sec-InitializeDateTimeFormat
• LDMLNumberingSystemKey should not be | string. See https://ecma-international.org/ecma-402/7.0/index.html table 4. Future addition to this will require a Normative spec change. See https://github.com/tc39/ecma402/pull/438 for example.
• ScriptCode should just be string.

The main reason for string type instead of enum is bc ECMA402 does not require CLDR so those are considered implementation details. You can have a runtime env that does not support those things.

[longlho]

@RyanCavanaugh shouldn't the criteria be stage 4? Stage 4 does include adoption criteria of at least 2 tst262-compatible implementations

[Dangoo]

@longlho thanks for your comments.
I brought it up as draft PR against this repo and removed the enum for numberingSystem as well.
Let's see when we get green lights from the maintainers for this.

It appears Intl.Locale will be available with Safari 14:

[orta]

Yeah, this should be OK to go now, tested it in Firefox too. 👍

[hbroer]

Hi, I need the types for a project. I have copied it from the PR to a .d.ts file but that only works while development within jest. I can't build it with my tooling (microbundle -> rollup -> rollup-plugin-typescript2) because the types are missing then. I did not found any @types or other solution to get it working. I wonder that this types is not supported by typescript at esnext/es2020 yet. Has anyone a idea how to add the types until this is supported by TS?

[longlho]

You can use @formatjs/intl-locale

[hbroer]

Thanks @longlho will try that out.

[hbroer]

Could not get it (@formatjs/intl-locale) to work as a source of the types for Intl.Locale. The package exports a class Locale but does not extend the Intl namespace with Locale. It seems all of their polyfills need the es typescript types right and that's not possible for Intl.Locale (and what this issues is about).

So I don't get the point why this (Stage 4 since February) is still not included in the es2020/esnext types. In my opinion the types should be published before the polyfills. Getting types from a polyfill and "hack" them into a project feels the wrong way (same for copy and paste types from PR). Don't see any reason why a Stage 4 Feature should wait for the browsers. Then we could still wait for some features because of Apples "let's do it our incompatible way" Safari or the Mozilla "the specs only say it has to provide this properties, not that the values make sense" Firefox. ^^

[longlho]

u can just add a

import {Locale} from '@formatjs/intl-locale'
declare global {
    namespace Intl {
        const Locale: Locale
    }
}

to a d.ts file or the like.

Unfortunately the rate of merging PR seems quite slow.

[hbroer]

@longlho that brought me on the right way. But not declaring in a d.ts file. That would still break the build. But inside of my main entry point which only exports the main components:

// eslint-disable-next-line @typescript-eslint/no-unused-vars
import type {Locale as FormatJsLocale, IntlLocaleOptions} from '@formatjs/intl-locale'
declare global {
    // eslint-disable-next-line @typescript-eslint/no-namespace
    namespace Intl {
        type Locale = FormatJsLocale;
        const Locale: {
            new (tag?: string, options?: IntlLocaleOptions): Locale;
        };
    }
}

export * from "./lib/translator";

Thanks for that. 👍 Now I can keep working on that library. ❤️