1/*! ***************************************************************************** 2Copyright (c) Microsoft Corporation. All rights reserved. 3Licensed under the Apache License, Version 2.0 (the "License"); you may not use 4this file except in compliance with the License. You may obtain a copy of the 5License at http://www.apache.org/licenses/LICENSE-2.0 6 7THIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 8KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED 9WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE, 10MERCHANTABLITY OR NON-INFRINGEMENT. 11 12See the Apache Version 2.0 License for specific language governing permissions 13and limitations under the License. 14***************************************************************************** */ 15 16 17 18/// <reference no-default-lib="true"/> 19 20 21/// <reference lib="es2018.intl" /> 22declare 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 | readonly (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} 434