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