1 | /*! *****************************************************************************
|
2 | Copyright (c) Microsoft Corporation. All rights reserved.
|
3 | Licensed under the Apache License, Version 2.0 (the "License"); you may not use
|
4 | this file except in compliance with the License. You may obtain a copy of the
|
5 | License at http://www.apache.org/licenses/LICENSE-2.0
|
6 |
|
7 | THIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
8 | KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
|
9 | WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
|
10 | MERCHANTABLITY OR NON-INFRINGEMENT.
|
11 |
|
12 | See the Apache Version 2.0 License for specific language governing permissions
|
13 | and limitations under the License.
|
14 | ***************************************************************************** */
|
15 |
|
16 |
|
17 |
|
18 | /// <reference no-default-lib="true"/>
|
19 |
|
20 |
|
21 | /// <reference lib="es2018.intl" />
|
22 | declare namespace Intl {
|
23 |
|
24 | /**
|
25 | * [Unicode BCP 47 Locale Identifiers](https://unicode.org/reports/tr35/#Unicode_Language_and_Locale_Identifiers) definition.
|
26 | *
|
27 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
|
28 | */
|
29 | type UnicodeBCP47LocaleIdentifier = string;
|
30 |
|
31 | /**
|
32 | * Unit to use in the relative time internationalized message.
|
33 | *
|
34 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/format#Parameters).
|
35 | */
|
36 | type RelativeTimeFormatUnit =
|
37 | | "year"
|
38 | | "years"
|
39 | | "quarter"
|
40 | | "quarters"
|
41 | | "month"
|
42 | | "months"
|
43 | | "week"
|
44 | | "weeks"
|
45 | | "day"
|
46 | | "days"
|
47 | | "hour"
|
48 | | "hours"
|
49 | | "minute"
|
50 | | "minutes"
|
51 | | "second"
|
52 | | "seconds";
|
53 |
|
54 | /**
|
55 | * Value of the `unit` property in objects returned by
|
56 | * `Intl.RelativeTimeFormat.prototype.formatToParts()`. `formatToParts` and
|
57 | * `format` methods accept either singular or plural unit names as input,
|
58 | * but `formatToParts` only outputs singular (e.g. "day") not plural (e.g.
|
59 | * "days").
|
60 | *
|
61 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/formatToParts#Using_formatToParts).
|
62 | */
|
63 | type RelativeTimeFormatUnitSingular =
|
64 | | "year"
|
65 | | "quarter"
|
66 | | "month"
|
67 | | "week"
|
68 | | "day"
|
69 | | "hour"
|
70 | | "minute"
|
71 | | "second";
|
72 |
|
73 | /**
|
74 | * The locale matching algorithm to use.
|
75 | *
|
76 | * [MDN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation).
|
77 | */
|
78 | type RelativeTimeFormatLocaleMatcher = "lookup" | "best fit";
|
79 |
|
80 | /**
|
81 | * The format of output message.
|
82 | *
|
83 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
|
84 | */
|
85 | type RelativeTimeFormatNumeric = "always" | "auto";
|
86 |
|
87 | /**
|
88 | * The length of the internationalized message.
|
89 | *
|
90 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
|
91 | */
|
92 | type RelativeTimeFormatStyle = "long" | "short" | "narrow";
|
93 |
|
94 | /**
|
95 | * [BCP 47 language tag](http://tools.ietf.org/html/rfc5646) definition.
|
96 | *
|
97 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
|
98 | */
|
99 | type BCP47LanguageTag = string;
|
100 |
|
101 | /**
|
102 | * The locale(s) to use
|
103 | *
|
104 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
|
105 | */
|
106 | type LocalesArgument = UnicodeBCP47LocaleIdentifier | Locale | (UnicodeBCP47LocaleIdentifier | Locale)[] | undefined;
|
107 |
|
108 | /**
|
109 | * An object with some or all of properties of `options` parameter
|
110 | * of `Intl.RelativeTimeFormat` constructor.
|
111 | *
|
112 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
|
113 | */
|
114 | interface RelativeTimeFormatOptions {
|
115 | /** The locale matching algorithm to use. For information about this option, see [Intl page](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation). */
|
116 | localeMatcher?: RelativeTimeFormatLocaleMatcher;
|
117 | /** The format of output message. */
|
118 | numeric?: RelativeTimeFormatNumeric;
|
119 | /** The length of the internationalized message. */
|
120 | style?: RelativeTimeFormatStyle;
|
121 | }
|
122 |
|
123 | /**
|
124 | * An object with properties reflecting the locale
|
125 | * and formatting options computed during initialization
|
126 | * of the `Intl.RelativeTimeFormat` object
|
127 | *
|
128 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/resolvedOptions#Description).
|
129 | */
|
130 | interface ResolvedRelativeTimeFormatOptions {
|
131 | locale: UnicodeBCP47LocaleIdentifier;
|
132 | style: RelativeTimeFormatStyle;
|
133 | numeric: RelativeTimeFormatNumeric;
|
134 | numberingSystem: string;
|
135 | }
|
136 |
|
137 | /**
|
138 | * An object representing the relative time format in parts
|
139 | * that can be used for custom locale-aware formatting.
|
140 | *
|
141 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/formatToParts#Using_formatToParts).
|
142 | */
|
143 | type RelativeTimeFormatPart =
|
144 | | {
|
145 | type: "literal";
|
146 | value: string;
|
147 | }
|
148 | | {
|
149 | type: Exclude<NumberFormatPartTypes, "literal">;
|
150 | value: string;
|
151 | unit: RelativeTimeFormatUnitSingular;
|
152 | };
|
153 |
|
154 | interface RelativeTimeFormat {
|
155 | /**
|
156 | * Formats a value and a unit according to the locale
|
157 | * and formatting options of the given
|
158 | * [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat)
|
159 | * object.
|
160 | *
|
161 | * While this method automatically provides the correct plural forms,
|
162 | * the grammatical form is otherwise as neutral as possible.
|
163 | *
|
164 | * It is the caller's responsibility to handle cut-off logic
|
165 | * such as deciding between displaying "in 7 days" or "in 1 week".
|
166 | * This API does not support relative dates involving compound units.
|
167 | * e.g "in 5 days and 4 hours".
|
168 | *
|
169 | * @param value - Numeric value to use in the internationalized relative time message
|
170 | *
|
171 | * @param unit - [Unit](https://tc39.es/ecma402/#sec-singularrelativetimeunit) to use in the relative time internationalized message.
|
172 | *
|
173 | * @throws `RangeError` if `unit` was given something other than `unit` possible values
|
174 | *
|
175 | * @returns {string} Internationalized relative time message as string
|
176 | *
|
177 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/format).
|
178 | */
|
179 | format(value: number, unit: RelativeTimeFormatUnit): string;
|
180 |
|
181 | /**
|
182 | * Returns an array of objects representing the relative time format in parts that can be used for custom locale-aware formatting.
|
183 | *
|
184 | * @param value - Numeric value to use in the internationalized relative time message
|
185 | *
|
186 | * @param unit - [Unit](https://tc39.es/ecma402/#sec-singularrelativetimeunit) to use in the relative time internationalized message.
|
187 | *
|
188 | * @throws `RangeError` if `unit` was given something other than `unit` possible values
|
189 | *
|
190 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/formatToParts).
|
191 | */
|
192 | formatToParts(value: number, unit: RelativeTimeFormatUnit): RelativeTimeFormatPart[];
|
193 |
|
194 | /**
|
195 | * Provides access to the locale and options computed during initialization of this `Intl.RelativeTimeFormat` object.
|
196 | *
|
197 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/resolvedOptions).
|
198 | */
|
199 | resolvedOptions(): ResolvedRelativeTimeFormatOptions;
|
200 | }
|
201 |
|
202 | /**
|
203 | * The [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat)
|
204 | * object is a constructor for objects that enable language-sensitive relative time formatting.
|
205 | *
|
206 | * [Compatibility](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat#Browser_compatibility).
|
207 | */
|
208 | const RelativeTimeFormat: {
|
209 | /**
|
210 | * Creates [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat) objects
|
211 | *
|
212 | * @param locales - A string with a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646), or an array of such strings.
|
213 | * For the general form and interpretation of the locales argument,
|
214 | * see the [`Intl` page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation).
|
215 | *
|
216 | * @param options - An [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters)
|
217 | * with some or all of options of `RelativeTimeFormatOptions`.
|
218 | *
|
219 | * @returns [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat) object.
|
220 | *
|
221 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat).
|
222 | */
|
223 | new(
|
224 | locales?: UnicodeBCP47LocaleIdentifier | UnicodeBCP47LocaleIdentifier[],
|
225 | options?: RelativeTimeFormatOptions,
|
226 | ): RelativeTimeFormat;
|
227 |
|
228 | /**
|
229 | * Returns an array containing those of the provided locales
|
230 | * that are supported in date and time formatting
|
231 | * without having to fall back to the runtime's default locale.
|
232 | *
|
233 | * @param locales - A string with a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646), or an array of such strings.
|
234 | * For the general form and interpretation of the locales argument,
|
235 | * see the [`Intl` page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation).
|
236 | *
|
237 | * @param options - An [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters)
|
238 | * with some or all of options of the formatting.
|
239 | *
|
240 | * @returns An array containing those of the provided locales
|
241 | * that are supported in date and time formatting
|
242 | * without having to fall back to the runtime's default locale.
|
243 | *
|
244 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/supportedLocalesOf).
|
245 | */
|
246 | supportedLocalesOf(
|
247 | locales?: UnicodeBCP47LocaleIdentifier | UnicodeBCP47LocaleIdentifier[],
|
248 | options?: RelativeTimeFormatOptions,
|
249 | ): UnicodeBCP47LocaleIdentifier[];
|
250 | };
|
251 |
|
252 | interface NumberFormatOptions {
|
253 | compactDisplay?: "short" | "long" | undefined;
|
254 | notation?: "standard" | "scientific" | "engineering" | "compact" | undefined;
|
255 | signDisplay?: "auto" | "never" | "always" | "exceptZero" | undefined;
|
256 | unit?: string | undefined;
|
257 | unitDisplay?: "short" | "long" | "narrow" | undefined;
|
258 | currencyDisplay?: string | undefined;
|
259 | currencySign?: string | undefined;
|
260 | }
|
261 |
|
262 | interface ResolvedNumberFormatOptions {
|
263 | compactDisplay?: "short" | "long";
|
264 | notation?: "standard" | "scientific" | "engineering" | "compact";
|
265 | signDisplay?: "auto" | "never" | "always" | "exceptZero";
|
266 | unit?: string;
|
267 | unitDisplay?: "short" | "long" | "narrow";
|
268 | currencyDisplay?: string;
|
269 | currencySign?: string;
|
270 | }
|
271 |
|
272 | interface DateTimeFormatOptions {
|
273 | calendar?: string | undefined;
|
274 | dayPeriod?: "narrow" | "short" | "long" | undefined;
|
275 | numberingSystem?: string | undefined;
|
276 |
|
277 | dateStyle?: "full" | "long" | "medium" | "short" | undefined;
|
278 | timeStyle?: "full" | "long" | "medium" | "short" | undefined;
|
279 | hourCycle?: "h11" | "h12" | "h23" | "h24" | undefined;
|
280 | }
|
281 |
|
282 | type LocaleHourCycleKey = "h12" | "h23" | "h11" | "h24";
|
283 | type LocaleCollationCaseFirst = "upper" | "lower" | "false";
|
284 |
|
285 | interface LocaleOptions {
|
286 | /** A string containing the language, and the script and region if available. */
|
287 | baseName?: string;
|
288 | /** The part of the Locale that indicates the locale's calendar era. */
|
289 | calendar?: string;
|
290 | /** Flag that defines whether case is taken into account for the locale's collation rules. */
|
291 | caseFirst?: LocaleCollationCaseFirst;
|
292 | /** The collation type used for sorting */
|
293 | collation?: string;
|
294 | /** The time keeping format convention used by the locale. */
|
295 | hourCycle?: LocaleHourCycleKey;
|
296 | /** The primary language subtag associated with the locale. */
|
297 | language?: string;
|
298 | /** The numeral system used by the locale. */
|
299 | numberingSystem?: string;
|
300 | /** Flag that defines whether the locale has special collation handling for numeric characters. */
|
301 | numeric?: boolean;
|
302 | /** The region of the world (usually a country) associated with the locale. Possible values are region codes as defined by ISO 3166-1. */
|
303 | region?: string;
|
304 | /** The script used for writing the particular language used in the locale. Possible values are script codes as defined by ISO 15924. */
|
305 | script?: string;
|
306 | }
|
307 |
|
308 | interface Locale extends LocaleOptions {
|
309 | /** A string containing the language, and the script and region if available. */
|
310 | baseName: string;
|
311 | /** The primary language subtag associated with the locale. */
|
312 | language: string;
|
313 | /** Gets the most likely values for the language, script, and region of the locale based on existing values. */
|
314 | maximize(): Locale;
|
315 | /** Attempts to remove information about the locale that would be added by calling `Locale.maximize()`. */
|
316 | minimize(): Locale;
|
317 | /** Returns the locale's full locale identifier string. */
|
318 | toString(): BCP47LanguageTag;
|
319 | }
|
320 |
|
321 | /**
|
322 | * Constructor creates [Intl.Locale](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale)
|
323 | * objects
|
324 | *
|
325 | * @param tag - A string with a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646).
|
326 | * For the general form and interpretation of the locales argument,
|
327 | * see the [`Intl` page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation).
|
328 | *
|
329 | * @param options - An [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/Locale#Parameters) with some or all of options of the locale.
|
330 | *
|
331 | * @returns [Intl.Locale](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) object.
|
332 | *
|
333 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale).
|
334 | */
|
335 | const Locale: {
|
336 | new (tag: BCP47LanguageTag | Locale, options?: LocaleOptions): Locale;
|
337 | };
|
338 |
|
339 | type DisplayNamesFallback =
|
340 | | "code"
|
341 | | "none";
|
342 |
|
343 | type DisplayNamesType =
|
344 | | "language"
|
345 | | "region"
|
346 | | "script"
|
347 | | "calendar"
|
348 | | "dateTimeField"
|
349 | | "currency";
|
350 |
|
351 | type DisplayNamesLanguageDisplay =
|
352 | | "dialect"
|
353 | | "standard";
|
354 |
|
355 | interface DisplayNamesOptions {
|
356 | localeMatcher?: RelativeTimeFormatLocaleMatcher;
|
357 | style?: RelativeTimeFormatStyle;
|
358 | type: DisplayNamesType;
|
359 | languageDisplay?: DisplayNamesLanguageDisplay;
|
360 | fallback?: DisplayNamesFallback;
|
361 | }
|
362 |
|
363 | interface ResolvedDisplayNamesOptions {
|
364 | locale: UnicodeBCP47LocaleIdentifier;
|
365 | style: RelativeTimeFormatStyle;
|
366 | type: DisplayNamesType;
|
367 | fallback: DisplayNamesFallback;
|
368 | languageDisplay?: DisplayNamesLanguageDisplay;
|
369 | }
|
370 |
|
371 | interface DisplayNames {
|
372 | /**
|
373 | * Receives a code and returns a string based on the locale and options provided when instantiating
|
374 | * [`Intl.DisplayNames()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames)
|
375 | *
|
376 | * @param code The `code` to provide depends on the `type` passed to display name during creation:
|
377 | * - If the type is `"region"`, code should be either an [ISO-3166 two letters region code](https://www.iso.org/iso-3166-country-codes.html),
|
378 | * or a [three digits UN M49 Geographic Regions](https://unstats.un.org/unsd/methodology/m49/).
|
379 | * - If the type is `"script"`, code should be an [ISO-15924 four letters script code](https://unicode.org/iso15924/iso15924-codes.html).
|
380 | * - If the type is `"language"`, code should be a `languageCode` ["-" `scriptCode`] ["-" `regionCode` ] *("-" `variant` )
|
381 | * subsequence of the unicode_language_id grammar in [UTS 35's Unicode Language and Locale Identifiers grammar](https://unicode.org/reports/tr35/#Unicode_language_identifier).
|
382 | * `languageCode` is either a two letters ISO 639-1 language code or a three letters ISO 639-2 language code.
|
383 | * - If the type is `"currency"`, code should be a [3-letter ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html).
|
384 | *
|
385 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames/of).
|
386 | */
|
387 | of(code: string): string | undefined;
|
388 | /**
|
389 | * Returns a new object with properties reflecting the locale and style formatting options computed during the construction of the current
|
390 | * [`Intl/DisplayNames`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames) object.
|
391 | *
|
392 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames/resolvedOptions).
|
393 | */
|
394 | resolvedOptions(): ResolvedDisplayNamesOptions;
|
395 | }
|
396 |
|
397 | /**
|
398 | * The [`Intl.DisplayNames()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames)
|
399 | * object enables the consistent translation of language, region and script display names.
|
400 | *
|
401 | * [Compatibility](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames#browser_compatibility).
|
402 | */
|
403 | const DisplayNames: {
|
404 | prototype: DisplayNames;
|
405 |
|
406 | /**
|
407 | * @param locales A string with a BCP 47 language tag, or an array of such strings.
|
408 | * For the general form and interpretation of the `locales` argument, see the [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation)
|
409 | * page.
|
410 | *
|
411 | * @param options An object for setting up a display name.
|
412 | *
|
413 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames/DisplayNames).
|
414 | */
|
415 | new(locales: LocalesArgument, options: DisplayNamesOptions): DisplayNames;
|
416 |
|
417 | /**
|
418 | * Returns an array containing those of the provided locales that are supported in display names without having to fall back to the runtime's default locale.
|
419 | *
|
420 | * @param locales A string with a BCP 47 language tag, or an array of such strings.
|
421 | * For the general form and interpretation of the `locales` argument, see the [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation)
|
422 | * page.
|
423 | *
|
424 | * @param options An object with a locale matcher.
|
425 | *
|
426 | * @returns An array of strings representing a subset of the given locale tags that are supported in display names without having to fall back to the runtime's default locale.
|
427 | *
|
428 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames/supportedLocalesOf).
|
429 | */
|
430 | supportedLocalesOf(locales?: LocalesArgument, options?: { localeMatcher?: RelativeTimeFormatLocaleMatcher }): BCP47LanguageTag[];
|
431 | };
|
432 |
|
433 | }
|