@juit/vue-i18n 0.4.0 → 1.0.0

package/dist/index.d.ts

@@ -1,29 +1,27 @@
 import { App } from 'vue';
 
-/** Base translations, either required when languages are set or all optional */
+/** Base languages are required for a configured subset; otherwise all are optional. */
 declare type BaseTranslation = ISOLanguage extends Language ? {
-    readonly [key in ISOLanguage]?: string;
+    readonly [key in ISOLanguage]?: TranslationMessage;
 } : {
-    readonly [key in Language]: string;
+    readonly [key in Language]: TranslationMessage;
 };
 
 /**
- * The date input type for date and time translation
+ * Accepted inputs for date and time formatting.
  *
- * When the input is a non-empty `string`, or a `number`, it will be constructed
- * into a `Date` object before being formatted.
+ * A non-empty string or a number is passed to the `Date` constructor before
+ * formatting. Numbers represent milliseconds since the Unix epoch.
  *
- * When the input is `null`, `undefined`, or an empty string, formatted result
- * will be a simple empty string.
+ * A `null`, `undefined`, or empty string input produces an empty string.
  */
 export declare type DateInput = Date | string | number | null | undefined;
 
 /**
- * All known date and time formats aliases.
+ * Supported date and time format aliases.
  *
- * When the `I18nConfig` interface is properly merged with and its contains
- * the `dateTimeFormats` property, this type will represent the list of
- * date and time formats available to the `d(...)` method.
+ * `I18nConfiguration.dateTimeFormats` defines the custom aliases accepted
+ * by `d(...)`. Built-in aliases remain available.
  *
  * When left unconfigured, this type will be `string`.
  */
@@ -43,14 +41,14 @@ export declare type DateTimeFormatAlias = ExtractConfig<I18nConfiguration, strin
  *   long: { dateStyle: 'long', timeStyle: 'long' },
  *   full: { dateStyle: 'full', timeStyle: 'full' },
  *
- *   // date only formats
+ *   // Formats for dates only
  *   date: { dateStyle: 'medium' },
  *   shortDate: { dateStyle: 'short' },
  *   mediumDate: { dateStyle: 'medium' },
  *   longDate: { dateStyle: 'long' },
  *   fullDate: { dateStyle: 'full' },
  *
- *   // time only formats
+ *   // Formats for times only
  *   time: { timeStyle: 'medium' },
  *   shortTime: { timeStyle: 'short' },
  *   mediumTime: { timeStyle: 'medium' },
@@ -63,15 +61,15 @@ export declare interface DateTimeFormats {
     readonly [key: string]: Intl.DateTimeFormatOptions;
 }
 
-/** The language or locale to use at construction */
+/** The initial language or locale; only its language and region are retained. */
 export declare type DefaultLanguage = ISOLanguage | `${ISOLanguage}-${string}` | Intl.Locale;
 
-/** Extended translations, supporting multiple region of each language */
+/** Optional regional variants of each supported language. */
 declare type ExtendedTranslation = {
-    readonly [key in `${Language}-${string}`]?: string;
+    readonly [key in `${Language}-${string}`]?: TranslationMessage;
 };
 
-/** Extract the value associated with key `K` from type `T` if it extends `R`, otherwise return `R` */
+/** Extract `T[K]` when present and assignable to `R`; otherwise fall back to `R`. */
 declare type ExtractConfig<T, R, K extends string> = T extends {
     [X in K]: infer V;
 } ? V extends R ? V : R : R;
@@ -80,24 +78,24 @@ declare type ExtractConfig<T, R, K extends string> = T extends {
 export declare function i18n(app: App, optionsOrLanguage: Language | I18nOptions): App;
 
 /**
- * I18n Configuration interface (to be merged with the actual configuration).
+ * Application configuration types, supplied through declaration merging.
  *
  * This interface (intentionally empty) is used to merge the actual per-app
  * configuration of the translation system, in order to provide the correct
  * types to the rest of the system.
  *
- * Two properties are expected to be defined in the configuration:
+ * The following properties can be defined as unions of string literals:
  *
- * * `languages`: the list of supported languages for the application. Those
- *                are ISO 639-1 language codes, and when specified, _every_
- *                translation _must_ include a translation for each.
- * * `translationKeys`: the list of translation keys known by the application.
+ * * `languages`: the supported ISO 639-1 language codes. When configured
+ *                with a subset of codes, each translation must include
+ *                a message for every base language in that subset.
+ * * `translationKeys`: the translation keys known by the application.
  *                      Those are the arbitrary keys used to identify the
- *                      messages to be  translated with the `t` and `tc`
+ *                      messages to be translated with the `t` and `tc`
  *                      methods of `Translator`.
- * * `dateTimeFormats`: the date and time formats _aliases_ used by the
+ * * `dateTimeFormats`: the date and time format _aliases_ used by the
  *                      application.
- * * `numberFormats`: the number formats _aliases_ used by the application.
+ * * `numberFormats`: the number format _aliases_ used by the application.
  *
  * To configure the types, follow the example below:
  *
@@ -145,30 +143,30 @@ export declare interface I18nOptions {
     numberFormats?: NumberFormats;
 }
 
-/** Type guard to check if a value is a valid ISO-3166-1 country code */
+/** Check whether a value is a country code in ISO_COUNTRIES, including XK. */
 export declare function isISOCountry(value: unknown): value is ISOCountry;
 
-/** Type guard to check if a value is a valid ISO-4217 currency code */
+/** Check runtime currency support; the static type may differ from the runtime's codes. */
 export declare function isISOCurrency(value: unknown): value is ISOCurrency;
 
-/** Type guard to check if a value is a valid ISO-639-1 language code */
+/** Check whether a value is an ISO 639-1 language code in ISO_LANGUAGES. */
 export declare function isISOLanguage(value: unknown): value is ISOLanguage;
 
-/** The array of all known ISO-3166-1 countries */
-export declare const ISO_COUNTRIES: ISOCountry[];
+/** Frozen, sorted ISO 3166-1 country codes, plus the CLDR code XK for Kosovo. */
+export declare const ISO_COUNTRIES: readonly (keyof ISOCountries)[];
 
-/** The array of all known ISO-639-1 languages */
-export declare const ISO_CURRENCIES: ISOCurrency[];
+/** Frozen currency codes reported by the runtime; these may differ from the static reference type. */
+export declare const ISO_CURRENCIES: readonly (keyof ISOCurrencies)[];
 
-/** The array of all known ISO-639-1 languages */
-export declare const ISO_LANGUAGES: ISOLanguage[];
+/** Frozen, sorted array of ISO 639-1 language codes. */
+export declare const ISO_LANGUAGES: readonly (keyof ISOLanguages)[];
 
-/** All known ISO-3166-1 countries and their names */
+/** Reference country codes and names, including the CLDR code XK for Kosovo. */
 export declare type ISOCountries = {
     AD: 'Andorra';
     AE: 'United Arab Emirates';
     AF: 'Afghanistan';
-    AG: 'Antigua & Barbuda';
+    AG: 'Antigua and Barbuda';
     AI: 'Anguilla';
     AL: 'Albania';
     AM: 'Armenia';
@@ -181,7 +179,7 @@ export declare type ISOCountries = {
     AW: 'Aruba';
     AX: 'Åland Islands';
     AZ: 'Azerbaijan';
-    BA: 'Bosnia & Herzegovina';
+    BA: 'Bosnia and Herzegovina';
     BB: 'Barbados';
     BD: 'Bangladesh';
     BE: 'Belgium';
@@ -190,11 +188,11 @@ export declare type ISOCountries = {
     BH: 'Bahrain';
     BI: 'Burundi';
     BJ: 'Benin';
-    BL: 'St. Barthélemy';
+    BL: 'Saint Barthélemy';
     BM: 'Bermuda';
-    BN: 'Brunei';
-    BO: 'Bolivia';
-    BQ: 'Caribbean Netherlands';
+    BN: 'Brunei Darussalam';
+    BO: 'Bolivia (Plurinational State of)';
+    BQ: 'Bonaire, Sint Eustatius and Saba';
     BR: 'Brazil';
     BS: 'Bahamas';
     BT: 'Bhutan';
@@ -204,9 +202,9 @@ export declare type ISOCountries = {
     BZ: 'Belize';
     CA: 'Canada';
     CC: 'Cocos (Keeling) Islands';
-    CD: 'Congo - Kinshasa';
+    CD: 'Congo (Democratic Republic of the)';
     CF: 'Central African Republic';
-    CG: 'Congo - Brazzaville';
+    CG: 'Congo';
     CH: 'Switzerland';
     CI: 'Côte d\'Ivoire';
     CK: 'Cook Islands';
@@ -216,7 +214,7 @@ export declare type ISOCountries = {
     CO: 'Colombia';
     CR: 'Costa Rica';
     CU: 'Cuba';
-    CV: 'Cape Verde';
+    CV: 'Cabo Verde';
     CW: 'Curaçao';
     CX: 'Christmas Island';
     CY: 'Cyprus';
@@ -236,12 +234,12 @@ export declare type ISOCountries = {
     ET: 'Ethiopia';
     FI: 'Finland';
     FJ: 'Fiji';
-    FK: 'Falkland Islands';
-    FM: 'Micronesia';
+    FK: 'Falkland Islands (Malvinas)';
+    FM: 'Micronesia (Federated States of)';
     FO: 'Faroe Islands';
     FR: 'France';
     GA: 'Gabon';
-    GB: 'United Kingdom';
+    GB: 'United Kingdom of Great Britain and Northern Ireland';
     GD: 'Grenada';
     GE: 'Georgia';
     GF: 'French Guiana';
@@ -254,13 +252,13 @@ export declare type ISOCountries = {
     GP: 'Guadeloupe';
     GQ: 'Equatorial Guinea';
     GR: 'Greece';
-    GS: 'South Georgia & South Sandwich Islands';
+    GS: 'South Georgia and the South Sandwich Islands';
     GT: 'Guatemala';
     GU: 'Guam';
     GW: 'Guinea-Bissau';
     GY: 'Guyana';
-    HK: 'Hong Kong SAR China';
-    HM: 'Heard & McDonald Islands';
+    HK: 'Hong Kong';
+    HM: 'Heard Island and McDonald Islands';
     HN: 'Honduras';
     HR: 'Croatia';
     HT: 'Haiti';
@@ -272,7 +270,7 @@ export declare type ISOCountries = {
     IN: 'India';
     IO: 'British Indian Ocean Territory';
     IQ: 'Iraq';
-    IR: 'Iran';
+    IR: 'Iran (Islamic Republic of)';
     IS: 'Iceland';
     IT: 'Italy';
     JE: 'Jersey';
@@ -284,15 +282,15 @@ export declare type ISOCountries = {
     KH: 'Cambodia';
     KI: 'Kiribati';
     KM: 'Comoros';
-    KN: 'St. Kitts & Nevis';
-    KP: 'North Korea';
-    KR: 'South Korea';
+    KN: 'Saint Kitts and Nevis';
+    KP: 'Korea (Democratic People\'s Republic of)';
+    KR: 'Korea (Republic of)';
     KW: 'Kuwait';
     KY: 'Cayman Islands';
     KZ: 'Kazakhstan';
-    LA: 'Laos';
+    LA: 'Lao People\'s Democratic Republic';
     LB: 'Lebanon';
-    LC: 'St. Lucia';
+    LC: 'Saint Lucia';
     LI: 'Liechtenstein';
     LK: 'Sri Lanka';
     LR: 'Liberia';
@@ -303,16 +301,16 @@ export declare type ISOCountries = {
     LY: 'Libya';
     MA: 'Morocco';
     MC: 'Monaco';
-    MD: 'Moldova';
+    MD: 'Moldova (Republic of)';
     ME: 'Montenegro';
-    MF: 'St. Martin';
+    MF: 'Saint Martin (French part)';
     MG: 'Madagascar';
     MH: 'Marshall Islands';
-    MK: 'North Macedonia';
+    MK: 'Macedonia (the former Yugoslav Republic of)';
     ML: 'Mali';
-    MM: 'Myanmar (Burma)';
+    MM: 'Myanmar';
     MN: 'Mongolia';
-    MO: 'Macao SAR China';
+    MO: 'Macao';
     MP: 'Northern Mariana Islands';
     MQ: 'Martinique';
     MR: 'Mauritania';
@@ -344,10 +342,10 @@ export declare type ISOCountries = {
     PH: 'Philippines';
     PK: 'Pakistan';
     PL: 'Poland';
-    PM: 'St. Pierre & Miquelon';
-    PN: 'Pitcairn Islands';
+    PM: 'Saint Pierre and Miquelon';
+    PN: 'Pitcairn';
     PR: 'Puerto Rico';
-    PS: 'Palestinian Territories';
+    PS: 'Palestine, State of';
     PT: 'Portugal';
     PW: 'Palau';
     PY: 'Paraguay';
@@ -355,7 +353,7 @@ export declare type ISOCountries = {
     RE: 'Réunion';
     RO: 'Romania';
     RS: 'Serbia';
-    RU: 'Russia';
+    RU: 'Russian Federation';
     RW: 'Rwanda';
     SA: 'Saudi Arabia';
     SB: 'Solomon Islands';
@@ -363,9 +361,9 @@ export declare type ISOCountries = {
     SD: 'Sudan';
     SE: 'Sweden';
     SG: 'Singapore';
-    SH: 'St. Helena';
+    SH: 'Saint Helena, Ascension and Tristan da Cunha';
     SI: 'Slovenia';
-    SJ: 'Svalbard & Jan Mayen';
+    SJ: 'Svalbard and Jan Mayen';
     SK: 'Slovakia';
     SL: 'Sierra Leone';
     SM: 'San Marino';
@@ -373,12 +371,12 @@ export declare type ISOCountries = {
     SO: 'Somalia';
     SR: 'Suriname';
     SS: 'South Sudan';
-    ST: 'São Tomé & Príncipe';
+    ST: 'Sao Tome and Principe';
     SV: 'El Salvador';
-    SX: 'Sint Maarten';
-    SY: 'Syria';
-    SZ: 'Eswatini';
-    TC: 'Turks & Caicos Islands';
+    SX: 'Sint Maarten (Dutch part)';
+    SY: 'Syrian Arab Republic';
+    SZ: 'Swaziland';
+    TC: 'Turks and Caicos Islands';
     TD: 'Chad';
     TF: 'French Southern Territories';
     TG: 'Togo';
@@ -389,25 +387,25 @@ export declare type ISOCountries = {
     TM: 'Turkmenistan';
     TN: 'Tunisia';
     TO: 'Tonga';
-    TR: 'Türkiye';
-    TT: 'Trinidad & Tobago';
+    TR: 'Turkey';
+    TT: 'Trinidad and Tobago';
     TV: 'Tuvalu';
-    TW: 'Taiwan';
-    TZ: 'Tanzania';
+    TW: 'Taiwan, Province of China[a]';
+    TZ: 'Tanzania, United Republic of';
     UA: 'Ukraine';
     UG: 'Uganda';
-    UM: 'U.S. Outlying Islands';
-    US: 'United States';
+    UM: 'United States Minor Outlying Islands';
+    US: 'United States of America';
     UY: 'Uruguay';
     UZ: 'Uzbekistan';
-    VA: 'Vatican City';
-    VC: 'St. Vincent & Grenadines';
-    VE: 'Venezuela';
-    VG: 'British Virgin Islands';
-    VI: 'U.S. Virgin Islands';
-    VN: 'Vietnam';
+    VA: 'Holy See';
+    VC: 'Saint Vincent and the Grenadines';
+    VE: 'Venezuela (Bolivarian Republic of)';
+    VG: 'Virgin Islands (British)';
+    VI: 'Virgin Islands (U.S.)';
+    VN: 'Viet Nam';
     VU: 'Vanuatu';
-    WF: 'Wallis & Futuna';
+    WF: 'Wallis and Futuna';
     WS: 'Samoa';
     XK: 'Kosovo';
     YE: 'Yemen';
@@ -417,10 +415,10 @@ export declare type ISOCountries = {
     ZW: 'Zimbabwe';
 };
 
-/** Array of all known ISO-3166-1 country names */
+/** Country code union derived from the reference table, including XK. */
 export declare type ISOCountry = keyof ISOCountries;
 
-/** All known ISO-4217 currencies and their name */
+/** Static reference currency codes and their names. */
 export declare type ISOCurrencies = {
     AED: 'United Arab Emirates Dirham';
     AFN: 'Afghan Afghani';
@@ -545,6 +543,7 @@ export declare type ISOCurrencies = {
     SEK: 'Swedish Krona';
     SGD: 'Singapore Dollar';
     SHP: 'St. Helena Pound';
+    SLE: 'Sierra Leonean Leone';
     SLL: 'Sierra Leonean Leone (1964—2022)';
     SOS: 'Somali Shilling';
     SRD: 'Surinamese Dollar';
@@ -573,6 +572,7 @@ export declare type ISOCurrencies = {
     WST: 'Samoan Tala';
     XAF: 'Central African CFA Franc';
     XCD: 'East Caribbean Dollar';
+    XCG: 'Caribbean Guilder';
     XDR: 'Special Drawing Rights';
     XOF: 'West African CFA Franc';
     XPF: 'CFP Franc';
@@ -580,19 +580,20 @@ export declare type ISOCurrencies = {
     YER: 'Yemeni Rial';
     ZAR: 'South African Rand';
     ZMW: 'Zambian Kwacha';
+    ZWG: 'Zimbabwe Gold';
     ZWL: 'Zimbabwean Dollar (2009)';
 };
 
-/** All known ISO-4217 currency codes */
+/** Currency code union derived from the static reference table. */
 export declare type ISOCurrency = keyof ISOCurrencies;
 
-/** All known ISO-639-1 language codes */
+/** Language code union derived from the reference table. */
 export declare type ISOLanguage = keyof ISOLanguages;
 
-/** All known ISO-639-1 languages and their name */
+/** ISO 639-1 language codes and their names. */
 export declare type ISOLanguages = {
     aa: 'Afar';
-    ab: 'Abkhazian';
+    ab: 'Abkhaz';
     ae: 'Avestan';
     af: 'Afrikaans';
     ak: 'Akan';
@@ -606,11 +607,11 @@ export declare type ISOLanguages = {
     ba: 'Bashkir';
     be: 'Belarusian';
     bg: 'Bulgarian';
-    bh: 'Bhojpuri';
+    bh: 'Bihari';
     bi: 'Bislama';
     bm: 'Bambara';
-    bn: 'Bangla';
-    bo: 'Tibetan';
+    bn: 'Bengali, Bangla';
+    bo: 'Tibetan Standard, Tibetan, Central';
     br: 'Breton';
     bs: 'Bosnian';
     ca: 'Catalan';
@@ -619,39 +620,39 @@ export declare type ISOLanguages = {
     co: 'Corsican';
     cr: 'Cree';
     cs: 'Czech';
-    cu: 'Church Slavic';
+    cu: 'Old Church Slavonic, Church Slavonic, Old Bulgarian';
     cv: 'Chuvash';
     cy: 'Welsh';
     da: 'Danish';
     de: 'German';
-    dv: 'Divehi';
+    dv: 'Divehi, Dhivehi, Maldivian';
     dz: 'Dzongkha';
     ee: 'Ewe';
-    el: 'Greek';
+    el: 'Greek (modern)';
     en: 'English';
     eo: 'Esperanto';
     es: 'Spanish';
     et: 'Estonian';
     eu: 'Basque';
-    fa: 'Persian';
-    ff: 'Fula';
+    fa: 'Persian (Farsi)';
+    ff: 'Fula, Fulah, Pulaar, Pular';
     fi: 'Finnish';
     fj: 'Fijian';
     fo: 'Faroese';
     fr: 'French';
     fy: 'Western Frisian';
     ga: 'Irish';
-    gd: 'Scottish Gaelic';
+    gd: 'Scottish Gaelic, Gaelic';
     gl: 'Galician';
-    gn: 'Guarani';
+    gn: 'Guaraní';
     gu: 'Gujarati';
     gv: 'Manx';
     ha: 'Hausa';
-    he: 'Hebrew';
+    he: 'Hebrew (modern)';
     hi: 'Hindi';
     ho: 'Hiri Motu';
     hr: 'Croatian';
-    ht: 'Haitian Creole';
+    ht: 'Haitian, Haitian Creole';
     hu: 'Hungarian';
     hy: 'Armenian';
     hz: 'Herero';
@@ -659,7 +660,7 @@ export declare type ISOLanguages = {
     id: 'Indonesian';
     ie: 'Interlingue';
     ig: 'Igbo';
-    ii: 'Sichuan Yi';
+    ii: 'Nuosu';
     ik: 'Inupiaq';
     io: 'Ido';
     is: 'Icelandic';
@@ -669,10 +670,10 @@ export declare type ISOLanguages = {
     jv: 'Javanese';
     ka: 'Georgian';
     kg: 'Kongo';
-    ki: 'Kikuyu';
-    kj: 'Kuanyama';
+    ki: 'Kikuyu, Gikuyu';
+    kj: 'Kwanyama, Kuanyama';
     kk: 'Kazakh';
-    kl: 'Kalaallisut';
+    kl: 'Kalaallisut, Greenlandic';
     km: 'Khmer';
     kn: 'Kannada';
     ko: 'Korean';
@@ -683,9 +684,9 @@ export declare type ISOLanguages = {
     kw: 'Cornish';
     ky: 'Kyrgyz';
     la: 'Latin';
-    lb: 'Luxembourgish';
+    lb: 'Luxembourgish, Letzeburgesch';
     lg: 'Ganda';
-    li: 'Limburgish';
+    li: 'Limburgish, Limburgan, Limburger';
     ln: 'Lingala';
     lo: 'Lao';
     lt: 'Lithuanian';
@@ -697,45 +698,45 @@ export declare type ISOLanguages = {
     mk: 'Macedonian';
     ml: 'Malayalam';
     mn: 'Mongolian';
-    mr: 'Marathi';
+    mr: 'Marathi (Marāṭhī)';
     ms: 'Malay';
     mt: 'Maltese';
     my: 'Burmese';
-    na: 'Nauru';
+    na: 'Nauruan';
     nb: 'Norwegian Bokmål';
-    nd: 'North Ndebele';
+    nd: 'Northern Ndebele';
     ne: 'Nepali';
     ng: 'Ndonga';
     nl: 'Dutch';
     nn: 'Norwegian Nynorsk';
     no: 'Norwegian';
-    nr: 'South Ndebele';
-    nv: 'Navajo';
-    ny: 'Nyanja';
+    nr: 'Southern Ndebele';
+    nv: 'Navajo, Navaho';
+    ny: 'Chichewa, Chewa, Nyanja';
     oc: 'Occitan';
-    oj: 'Ojibwa';
+    oj: 'Ojibwe, Ojibwa';
     om: 'Oromo';
-    or: 'Odia';
-    os: 'Ossetic';
-    pa: 'Punjabi';
-    pi: 'Pali';
+    or: 'Oriya';
+    os: 'Ossetian, Ossetic';
+    pa: '(Eastern) Punjabi';
+    pi: 'Pāli';
     pl: 'Polish';
-    ps: 'Pashto';
+    ps: 'Pashto, Pushto';
     pt: 'Portuguese';
     qu: 'Quechua';
     rm: 'Romansh';
-    rn: 'Rundi';
+    rn: 'Kirundi';
     ro: 'Romanian';
     ru: 'Russian';
     rw: 'Kinyarwanda';
-    sa: 'Sanskrit';
+    sa: 'Sanskrit (Saṁskṛta)';
     sc: 'Sardinian';
     sd: 'Sindhi';
     se: 'Northern Sami';
     sg: 'Sango';
-    si: 'Sinhala';
+    si: 'Sinhalese, Sinhala';
     sk: 'Slovak';
-    sl: 'Slovenian';
+    sl: 'Slovene';
     sm: 'Samoan';
     sn: 'Shona';
     so: 'Somali';
@@ -752,13 +753,13 @@ export declare type ISOLanguages = {
     th: 'Thai';
     ti: 'Tigrinya';
     tk: 'Turkmen';
-    tl: 'Filipino';
+    tl: 'Tagalog';
     tn: 'Tswana';
-    to: 'Tongan';
+    to: 'Tonga (Tonga Islands)';
     tr: 'Turkish';
     ts: 'Tsonga';
     tt: 'Tatar';
-    tw: 'Akan';
+    tw: 'Twi';
     ty: 'Tahitian';
     ug: 'Uyghur';
     uk: 'Ukrainian';
@@ -772,7 +773,7 @@ export declare type ISOLanguages = {
     xh: 'Xhosa';
     yi: 'Yiddish';
     yo: 'Yoruba';
-    za: 'Zhuang';
+    za: 'Zhuang, Chuang';
     zh: 'Chinese';
     zu: 'Zulu';
 };
@@ -780,15 +781,65 @@ export declare type ISOLanguages = {
 /** The languages configured in `I18nConfiguration` or all ISO languages */
 export declare type Language = ExtractConfig<I18nConfiguration, ISOLanguage, 'languages'>;
 
+/**
+ * A language matcher that determines the best matching language from a set
+ * of available languages.
+ */
+export declare interface LanguageMatcher<T extends readonly [ISOLanguage, ...ISOLanguage[]]> {
+    /** The list of available languages, with the first one being the default */
+    readonly availableLanguages: Readonly<T>;
+    /** The default language */
+    readonly defaultLanguage: T[0];
+    /**
+     * Determine the best matching language from the available languages.
+     *
+     * The first supported language in the input preference order is returned.
+     * Empty input or an input with no matches returns the default language.
+     *
+     * All languages here will be *normalized* before matching (for example
+     * `en-US` will be normalized to `en`, and `JA` will be normalized to `ja`).
+     *
+     * @param languages The language or list of languages to match against the
+     *                  available languages.
+     * @returns The best matching language from the available languages, or the
+     *          default language if no match is found.
+     */
+    match(languages: readonly string[] | string | undefined | null): T[number];
+}
+
+/** The {@link LanguageMatcher} constructor */
+export declare const LanguageMatcher: LanguageMatcherConstructor;
+
+declare interface LanguageMatcherConstructor {
+    /**
+     * Create a new {@link LanguageMatcher} instance matching *only* the single
+     * language specified.
+     *
+     * At runtime, the input is normalized. If it does not resolve to a valid
+     * ISO language code, an error is thrown.
+     */
+    new <L extends ISOLanguage>(availableLanguages: L): LanguageMatcher<[L]>;
+    /**
+     * Create a new {@link LanguageMatcher} instance matching the specified set
+     * of available languages.
+     *
+     * Typed inputs must be valid ISO language codes. At runtime, inputs are
+     * normalized and invalid entries are filtered out. The resulting list is
+     * copied, so later changes to the input array do not affect the matcher.
+     *
+     * If no valid ISO languages are provided, an error will be thrown.
+     */
+    new <const A extends readonly [ISOLanguage, ...ISOLanguage[]]>(availableLanguages: A): LanguageMatcher<A>;
+}
+
 /** Create a _reactive_ translator object from the given options */
 export declare function makeTranslator(options: I18nOptions): Translator;
 
 /**
- * All known number formats aliases.
+ * Supported number format aliases.
  *
- * When the `I18nConfig` interface is properly merged with and its contains
- * the `numberFormats` property, this type will represent the list of
- * date and time formats available to the `n(...)` method.
+ * `I18nConfiguration.numberFormats` defines the custom aliases accepted
+ * by `n(...)`. The `default` alias and currency code types remain available.
  *
  * When left unconfigured, this type will be `string`.
  */
@@ -805,7 +856,7 @@ export declare type NumberFormatAlias = ExtractConfig<I18nConfiguration, string,
  *   default: { }, // use the default number format
  *   EUR: { style: 'currency', currency: 'EUR' },
  *   USD: { style: 'currency', currency: 'USD' },
- *   // ... all currency codes can be used as aliases
+ *   // ... codes from ISO_CURRENCIES are available as aliases
  * }
  * ```
  */
@@ -813,7 +864,7 @@ export declare interface NumberFormats {
     readonly [key: string]: Intl.NumberFormatOptions;
 }
 
-/** Prettify our `Translations` exported type */
+/** Expand the properties of the exported `Translation` type for editor hints. */
 declare type PrettifyTranslation<T> = {
     [l in keyof T]: T[l];
 };
@@ -821,25 +872,26 @@ declare type PrettifyTranslation<T> = {
 /**
  * A type describing the translations for a given translation key.
  *
- * When the `I18nConfig` interface is properly merged with and its contains
- * the `languages` property, this type will represent the list of required
- * translation keys (languages) required for each translation.
- *
- * When left unconfigured, all ISO languages will be considered as optional.
+ * When `I18nConfiguration.languages` specifies a subset of ISO languages,
+ * every base language in that subset is required. Regional variants are
+ * optional. When unconfigured, or configured with all ISO languages, every
+ * language is optional.
  */
 export declare type Translation = PrettifyTranslation<BaseTranslation & ExtendedTranslation>;
 
 /**
  * All known translation keys.
  *
- * When the `I18nConfig` interface is properly merged with and its contains
- * the `translationKeys` property, this type will represent the list of
- * translations keys available to the `t(...)` and `tc(...)` methods.
+ * `I18nConfiguration.translationKeys` restricts the keys accepted by the
+ * `t(...)` and `tc(...)` methods and by `utils.updateTranslations(...)`.
  *
  * When left unconfigured, this type will be `string`.
  */
 export declare type TranslationKey = ExtractConfig<I18nConfiguration, string, 'translationKeys'>;
 
+/** A message with optional pipe-delimited variants, or a readonly tuple of one to three variants. */
+export declare type TranslationMessage = string | readonly [string, string?, string?];
+
 /**
  * Parameters for the formatting of a translation.
  *
@@ -847,8 +899,8 @@ export declare type TranslationKey = ExtractConfig<I18nConfiguration, string, 't
  * translator, allowing for the interpolation of values into the translated
  * message.
  *
- * When the parameter value is a number, it will be formatted using the `n`
- * formatter before being interpolated into the message.
+ * Numeric values use the current locale and the `default` number format
+ * before being interpolated into the message.
  */
 export declare interface TranslationParams {
     [key: string]: string | number;
@@ -857,9 +909,8 @@ export declare interface TranslationParams {
 /**
  * Options to initialize the translations handled by the translation system.
  *
- * Shared translations are defined as a key-value pair, where the key is the
- * identifier of the translation, and the value is an object containing the
- * translations for each language.
+ * Each key identifies a message, and its value maps languages and regional
+ * variants to message strings or plural tuples.
  */
 export declare interface Translations {
     readonly [key: string]: Translation;
@@ -871,67 +922,74 @@ export declare interface Translations {
  * This interface provides methods to translate messages, format numbers, and
  * format dates and times.
  *
- * Configured instances can be accessed using the `useI18n()` composition
+ * Configured instances can be accessed using the `useTranslator()` composition
  * function, which will provide an instance of the translator.
  */
 export declare interface Translator {
     /** The current ISO-639-1 language code used by this translator. */
     language: ISOLanguage;
-    /** The region (if any) used by thus translator to localize translations. */
+    /** The region (if any) used by this translator to localize translations. */
     region: ISOCountry | undefined;
-    /** The `Locale` used by this translator (merges `language` and `region`) */
+    /** The current locale. Assignments retain only the language and region. */
     locale: Readonly<Intl.Locale>;
     /**
      * Return the (possibly parameterized) translation for the specified message
      * in the current language.
      *
-     * Internally, this method uses the `tc(...)` function with `n=1`, in order to
-     * avoid duplication of message keys
+     * Delegates to `tc(...)` with `n=1`. A supplied `params.n` overrides this
+     * count, including for plural selection.
      */
     t(key: TranslationKey | Translation, params?: TranslationParams): string;
     /**
      * Return the (possibly parameterized) translation for the specified message
      * in the current language, with pluralization.
      *
-     * For pluralization, translation messages should be separated by the pipe
-     * character, like in Vue I18N. Example:
+     * String messages can contain variants separated by unescaped pipes:
      *
      * * `" one apple | {n} apples "` when _two_ translations are separated by a
-     *   pipe, the first will be used for singular, the second for zero or plural
+     *   pipe, the first is used for singular, and the second for zero or plural.
      * * `" no apples | one apple | {n} apples "` when _three_ translations are
      *   separated by a pipe, the first will be used for zero, the second for
-     *   singular, the second for zero or plural
+     *   singular, and the third for plural.
+     *
+     * Messages can also be readonly tuples: `[message]`, `[singular, plural]`,
+     * or `[zero, singular, plural]`. Pipes inside tuple elements are literal;
+     * placeholders and their escapes are still parsed.
      *
-     * For convenience, the `{n}` message parameter will always be contextualized
-     * with the number, unless overridden in the `params` themselves.
+     * The `{n}` parameter defaults to the supplied count. `params.n` overrides
+     * both its displayed value and plural selection. Zero and one select their
+     * respective variants; every other count selects the plural variant.
      */
     tc(key: TranslationKey | Translation, n: number, params?: TranslationParams): string;
     /**
-     * Format a number according to the current language.
+     * Format a number according to the current locale.
      *
      * When `format` is provided, it will be used to configure the number format.
-     * This can be one of the aliases specified at initialization, or a
-     * fully-fledged `Intl.NumberFormatOptions` object.
+     * Accepts a built-in or custom alias, or an `Intl.NumberFormatOptions`
+     * object. Omitting it selects the `default` alias. A null or undefined
+     * value produces an empty string.
      */
     n(value?: number | bigint | null | undefined, format?: NumberFormatAlias | Intl.NumberFormatOptions): string;
     /**
-     * Format date and time according to the current language.
+     * Format a date and time according to the current locale.
      *
      * When `format` is provided, it will be used to configure the date and time
-     * format. This can be one of the aliases specified at initialization, or a
-     * fully-fledged `Intl.DateTimeFormatOptions` object.
+     * format. Accepts a built-in or custom alias, or an
+     * `Intl.DateTimeFormatOptions` object. Omitting it selects the `default`
+     * alias. The explicit `timeZone` takes precedence over `format.timeZone`,
+     * then `defaultTimeZone`, then the runtime's time zone.
      */
     d(date?: DateInput, format?: DateTimeFormatAlias | Intl.DateTimeFormatOptions, timeZone?: string): string;
     /** Extra internationalization utilities */
     utils: {
         /**
          * Return the name of the language for the given ISO-639-1 code localized
-         * using the current language
+         * using the current locale.
          */
         language(code: ISOLanguage): string;
         /**
          * Return the name of the country (or region) for the given ISO-3166-1 code
-         * (or CLDR region code) using the current language
+         * (or CLDR region code) using the current locale.
          */
         country(code: ISOCountry | 'EU' | 'UN'): string;
         /**
@@ -940,13 +998,16 @@ export declare interface Translator {
          */
         flag(code: ISOCountry | 'EU' | 'UN'): string;
         /**
-         * Update the translations used by this translator.
+         * Merge translations and clear cached templates. Empty strings and
+         * undefined values are ignored; use a tuple containing an empty string
+         * for an intentionally blank message. Tuples are copied before storing.
+         * Updates affect subsequent calls but do not trigger reactive updates.
          */
         updateTranslations(translations: Partial<Record<TranslationKey, Partial<Translation>>>): void;
     };
 }
 
-/** Retrieve the translator instance from the Vue app */
+/** Retrieve the translator from the current Vue injection context, or throw if none is provided. */
 export declare function useTranslator(): Translator;
 
 export { }
@@ -961,11 +1022,11 @@ declare module 'vue' {
          * in the current language, with pluralization.
          */
         $tc: Translator['tc'];
-        /** Format a number into a string according to the current language */
+        /** Format a number into a string according to the current locale. */
         $n: Translator['n'];
         /**
-         * Format date and time using the specified style (defaults to `medium`)
-         * according to the current language
+         * Format a date and time using the current locale and the specified
+         * format, or the configurable `default` alias when omitted.
          */
         $d: Translator['d'];
     }