@juit/vue-i18n 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,705 @@
+import { App } from 'vue';
+
+/** Base translations, either required when languages are set or all optional */
+declare type BaseTranslation = ISOLanguage extends Language ? {
+    readonly [key in ISOLanguage]?: string;
+} : {
+    readonly [key in Language]: string;
+};
+
+/**
+ * The date input type for date and time translation
+ *
+ * When the input is a non-empty `string`, or a `number`, it will be constructed
+ * into a `Date` object before being formatted.
+ *
+ * When the input is `null`, `undefined`, or an empty string, formatted result
+ * will be a simple empty string.
+ */
+export declare type DateInput = Date | string | number | null | undefined;
+
+/**
+ * Options to initialize the date and time formats used by the translation
+ * system.
+ *
+ * * `dateTimeFormat`: the default format for times and dates used by `$d(...)`.
+ * * `dateOnlyFormat`: the default format for dates used by `$d.date(...)`.
+ * * `timeOnlyFormat`: the default format for times used by `$d.time(...)`.
+ * * `numberFormat`: the default format for numbers used by `$n(...)`.
+ */
+export declare interface DateTimeFormats {
+    dateOnlyFormat?: Intl.DateTimeFormatOptions | Intl.DateTimeFormatOptions['dateStyle'];
+    timeOnlyFormat?: Intl.DateTimeFormatOptions | Intl.DateTimeFormatOptions['timeStyle'];
+    dateTimeFormat?: Intl.DateTimeFormatOptions | (Intl.DateTimeFormatOptions['dateStyle'] & Intl.DateTimeFormatOptions['timeStyle']);
+    numberFormat?: Intl.NumberFormatOptions;
+}
+
+/** The language or locale to use at construction */
+export declare type DefaultLanguage = ISOLanguage | `${ISOLanguage}-${string}` | Intl.Locale;
+
+/** Extended translations, supporting multiple region of each language */
+declare type ExtendedTranslation = {
+    readonly [key in `${Language}-${string}`]?: string;
+};
+
+/** Extract the value associated with key `K` from type `T` if it extends `R`, otherwise return `R` */
+declare type ExtractConfig<T, R, K extends string> = T extends {
+    [X in K]: infer V;
+} ? V extends R ? V : R : R;
+
+/** Initialize the translation system plugin */
+export declare function i18n(app: App, optionsOrLanguage: Language | I18nOptions): App;
+
+/**
+ * I18n Configuration interface (to be merged with the actual configuration).
+ *
+ * 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:
+ *
+ * * `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.
+ *                      Those are the arbitrary keys used to identify the
+ *                      messages to be  translated with the `t` and `tc`
+ *                      methods of `Translator`.
+ *
+ * To configure the types, follow the example below:
+ *
+ * ```ts
+ * const translations = {
+ *   'hello': { en: 'Hello, world!', de: 'Hallo, Welt!' }
+ * } as const satisfies TranslationsOptions
+ *
+ * declare module '@juit/vue-i18n' {
+ *   export interface I18nConfiguration {
+ *     translationKeys: keyof typeof translations
+ *     languages: 'de' | 'en'
+ *   }
+ * }
+ * ```
+ */
+export declare interface I18nConfiguration {
+}
+
+/** Options to initialize the I18n plugin */
+export declare interface I18nOptions {
+    defaultLanguage: DefaultLanguage;
+    translations?: Translations;
+    formats?: DateTimeFormats;
+}
+
+/** Array of all known ISO-3166-1 countries */
+export declare type IsoCountries = {
+    AD: 'Andorra';
+    AE: 'United Arab Emirates';
+    AF: 'Afghanistan';
+    AG: 'Antigua & Barbuda';
+    AI: 'Anguilla';
+    AL: 'Albania';
+    AM: 'Armenia';
+    AO: 'Angola';
+    AQ: 'Antarctica';
+    AR: 'Argentina';
+    AS: 'American Samoa';
+    AT: 'Austria';
+    AU: 'Australia';
+    AW: 'Aruba';
+    AX: 'Åland Islands';
+    AZ: 'Azerbaijan';
+    BA: 'Bosnia & Herzegovina';
+    BB: 'Barbados';
+    BD: 'Bangladesh';
+    BE: 'Belgium';
+    BF: 'Burkina Faso';
+    BG: 'Bulgaria';
+    BH: 'Bahrain';
+    BI: 'Burundi';
+    BJ: 'Benin';
+    BL: 'St. Barthélemy';
+    BM: 'Bermuda';
+    BN: 'Brunei';
+    BO: 'Bolivia';
+    BQ: 'Caribbean Netherlands';
+    BR: 'Brazil';
+    BS: 'Bahamas';
+    BT: 'Bhutan';
+    BV: 'Bouvet Island';
+    BW: 'Botswana';
+    BY: 'Belarus';
+    BZ: 'Belize';
+    CA: 'Canada';
+    CC: 'Cocos (Keeling) Islands';
+    CF: 'Central African Republic';
+    CG: 'Congo - Brazzaville';
+    CH: 'Switzerland';
+    CI: 'Côte d\'Ivoire';
+    CK: 'Cook Islands';
+    CL: 'Chile';
+    CM: 'Cameroon';
+    CN: 'China';
+    CO: 'Colombia';
+    CR: 'Costa Rica';
+    CU: 'Cuba';
+    CV: 'Cape Verde';
+    CW: 'Curaçao';
+    CX: 'Christmas Island';
+    CY: 'Cyprus';
+    CZ: 'Czechia';
+    DE: 'Germany';
+    DJ: 'Djibouti';
+    DK: 'Denmark';
+    DM: 'Dominica';
+    DO: 'Dominican Republic';
+    DZ: 'Algeria';
+    EC: 'Ecuador';
+    EE: 'Estonia';
+    EG: 'Egypt';
+    EH: 'Western Sahara';
+    ER: 'Eritrea';
+    ES: 'Spain';
+    ET: 'Ethiopia';
+    FI: 'Finland';
+    FJ: 'Fiji';
+    FK: 'Falkland Islands';
+    FM: 'Micronesia';
+    FO: 'Faroe Islands';
+    FR: 'France';
+    GA: 'Gabon';
+    GB: 'United Kingdom';
+    GD: 'Grenada';
+    GE: 'Georgia';
+    GF: 'French Guiana';
+    GG: 'Guernsey';
+    GH: 'Ghana';
+    GI: 'Gibraltar';
+    GL: 'Greenland';
+    GM: 'Gambia';
+    GN: 'Guinea';
+    GP: 'Guadeloupe';
+    GQ: 'Equatorial Guinea';
+    GR: 'Greece';
+    GS: 'South Georgia & South Sandwich Islands';
+    GT: 'Guatemala';
+    GU: 'Guam';
+    GW: 'Guinea-Bissau';
+    GY: 'Guyana';
+    HK: 'Hong Kong SAR China';
+    HM: 'Heard & McDonald Islands';
+    HN: 'Honduras';
+    HR: 'Croatia';
+    HT: 'Haiti';
+    HU: 'Hungary';
+    ID: 'Indonesia';
+    IE: 'Ireland';
+    IL: 'Israel';
+    IM: 'Isle of Man';
+    IN: 'India';
+    IO: 'British Indian Ocean Territory';
+    IQ: 'Iraq';
+    IR: 'Iran';
+    IS: 'Iceland';
+    IT: 'Italy';
+    JE: 'Jersey';
+    JM: 'Jamaica';
+    JO: 'Jordan';
+    JP: 'Japan';
+    KE: 'Kenya';
+    KG: 'Kyrgyzstan';
+    KH: 'Cambodia';
+    KI: 'Kiribati';
+    KM: 'Comoros';
+    KN: 'St. Kitts & Nevis';
+    KP: 'North Korea';
+    KR: 'South Korea';
+    KW: 'Kuwait';
+    KY: 'Cayman Islands';
+    KZ: 'Kazakhstan';
+    LA: 'Laos';
+    LB: 'Lebanon';
+    LC: 'St. Lucia';
+    LI: 'Liechtenstein';
+    LK: 'Sri Lanka';
+    LR: 'Liberia';
+    LS: 'Lesotho';
+    LT: 'Lithuania';
+    LU: 'Luxembourg';
+    LV: 'Latvia';
+    LY: 'Libya';
+    MA: 'Morocco';
+    MC: 'Monaco';
+    MD: 'Moldova';
+    ME: 'Montenegro';
+    MF: 'St. Martin';
+    MG: 'Madagascar';
+    MH: 'Marshall Islands';
+    MK: 'North Macedonia';
+    ML: 'Mali';
+    MM: 'Myanmar (Burma)';
+    MN: 'Mongolia';
+    MO: 'Macao SAR China';
+    MP: 'Northern Mariana Islands';
+    MQ: 'Martinique';
+    MR: 'Mauritania';
+    MS: 'Montserrat';
+    MT: 'Malta';
+    MU: 'Mauritius';
+    MV: 'Maldives';
+    MW: 'Malawi';
+    MX: 'Mexico';
+    MY: 'Malaysia';
+    MZ: 'Mozambique';
+    NA: 'Namibia';
+    NC: 'New Caledonia';
+    NE: 'Niger';
+    NF: 'Norfolk Island';
+    NG: 'Nigeria';
+    NI: 'Nicaragua';
+    NL: 'Netherlands';
+    NO: 'Norway';
+    NP: 'Nepal';
+    NR: 'Nauru';
+    NU: 'Niue';
+    NZ: 'New Zealand';
+    OM: 'Oman';
+    PA: 'Panama';
+    PE: 'Peru';
+    PF: 'French Polynesia';
+    PG: 'Papua New Guinea';
+    PH: 'Philippines';
+    PK: 'Pakistan';
+    PL: 'Poland';
+    PM: 'St. Pierre & Miquelon';
+    PN: 'Pitcairn Islands';
+    PR: 'Puerto Rico';
+    PS: 'Palestinian Territories';
+    PT: 'Portugal';
+    PW: 'Palau';
+    PY: 'Paraguay';
+    QA: 'Qatar';
+    RE: 'Réunion';
+    RO: 'Romania';
+    RS: 'Serbia';
+    RU: 'Russia';
+    RW: 'Rwanda';
+    SA: 'Saudi Arabia';
+    SB: 'Solomon Islands';
+    SC: 'Seychelles';
+    SD: 'Sudan';
+    SE: 'Sweden';
+    SG: 'Singapore';
+    SH: 'St. Helena';
+    SI: 'Slovenia';
+    SJ: 'Svalbard & Jan Mayen';
+    SK: 'Slovakia';
+    SL: 'Sierra Leone';
+    SM: 'San Marino';
+    SN: 'Senegal';
+    SO: 'Somalia';
+    SR: 'Suriname';
+    SS: 'South Sudan';
+    ST: 'São Tomé & Príncipe';
+    SV: 'El Salvador';
+    SX: 'Sint Maarten';
+    SY: 'Syria';
+    SZ: 'Eswatini';
+    TC: 'Turks & Caicos Islands';
+    TD: 'Chad';
+    TF: 'French Southern Territories';
+    TG: 'Togo';
+    TH: 'Thailand';
+    TJ: 'Tajikistan';
+    TK: 'Tokelau';
+    TL: 'Timor-Leste';
+    TM: 'Turkmenistan';
+    TN: 'Tunisia';
+    TO: 'Tonga';
+    TR: 'Türkiye';
+    TT: 'Trinidad & Tobago';
+    TV: 'Tuvalu';
+    TW: 'Taiwan';
+    TZ: 'Tanzania';
+    UA: 'Ukraine';
+    UG: 'Uganda';
+    UM: 'U.S. Outlying Islands';
+    US: 'United States';
+    UY: 'Uruguay';
+    UZ: 'Uzbekistan';
+    VA: 'Vatican City';
+    VC: 'St. Vincent & Grenadines';
+    VE: 'Venezuela';
+    VG: 'British Virgin Islands';
+    VI: 'U.S. Virgin Islands';
+    VN: 'Vietnam';
+    VU: 'Vanuatu';
+    WF: 'Wallis & Futuna';
+    WS: 'Samoa';
+    YE: 'Yemen';
+    YT: 'Mayotte';
+    ZA: 'South Africa';
+    ZM: 'Zambia';
+    ZW: 'Zimbabwe';
+};
+
+/** Array of all known ISO-3166-1 countries */
+export declare type ISOCountry = keyof IsoCountries;
+
+/** All known ISO-639-1 languages */
+export declare type ISOLanguage = keyof IsoLanguages;
+
+/** Array of all known ISO-639-1 languages */
+export declare type IsoLanguages = {
+    aa: 'Afar';
+    ab: 'Abkhazian';
+    ae: 'Avestan';
+    af: 'Afrikaans';
+    ak: 'Akan';
+    am: 'Amharic';
+    an: 'Aragonese';
+    ar: 'Arabic';
+    as: 'Assamese';
+    av: 'Avaric';
+    ay: 'Aymara';
+    az: 'Azerbaijani';
+    ba: 'Bashkir';
+    be: 'Belarusian';
+    bg: 'Bulgarian';
+    bh: 'Bhojpuri';
+    bi: 'Bislama';
+    bm: 'Bambara';
+    bn: 'Bangla';
+    bo: 'Tibetan';
+    br: 'Breton';
+    bs: 'Bosnian';
+    ca: 'Catalan';
+    ce: 'Chechen';
+    ch: 'Chamorro';
+    co: 'Corsican';
+    cr: 'Cree';
+    cs: 'Czech';
+    cu: 'Church Slavic';
+    cv: 'Chuvash';
+    cy: 'Welsh';
+    da: 'Danish';
+    de: 'German';
+    dv: 'Divehi';
+    dz: 'Dzongkha';
+    ee: 'Ewe';
+    el: 'Greek';
+    en: 'English';
+    eo: 'Esperanto';
+    es: 'Spanish';
+    et: 'Estonian';
+    eu: 'Basque';
+    fa: 'Persian';
+    ff: 'Fula';
+    fi: 'Finnish';
+    fj: 'Fijian';
+    fo: 'Faroese';
+    fr: 'French';
+    fy: 'Western Frisian';
+    ga: 'Irish';
+    gd: 'Scottish Gaelic';
+    gl: 'Galician';
+    gn: 'Guarani';
+    gu: 'Gujarati';
+    gv: 'Manx';
+    ha: 'Hausa';
+    he: 'Hebrew';
+    hi: 'Hindi';
+    ho: 'Hiri Motu';
+    hr: 'Croatian';
+    ht: 'Haitian Creole';
+    hu: 'Hungarian';
+    hy: 'Armenian';
+    hz: 'Herero';
+    ia: 'Interlingua';
+    id: 'Indonesian';
+    ie: 'Interlingue';
+    ig: 'Igbo';
+    ii: 'Sichuan Yi';
+    ik: 'Inupiaq';
+    io: 'Ido';
+    is: 'Icelandic';
+    it: 'Italian';
+    iu: 'Inuktitut';
+    ja: 'Japanese';
+    jv: 'Javanese';
+    ka: 'Georgian';
+    kg: 'Kongo';
+    ki: 'Kikuyu';
+    kj: 'Kuanyama';
+    kk: 'Kazakh';
+    kl: 'Kalaallisut';
+    km: 'Khmer';
+    kn: 'Kannada';
+    ko: 'Korean';
+    kr: 'Kanuri';
+    ks: 'Kashmiri';
+    ku: 'Kurdish';
+    kv: 'Komi';
+    kw: 'Cornish';
+    ky: 'Kyrgyz';
+    la: 'Latin';
+    lb: 'Luxembourgish';
+    lg: 'Ganda';
+    li: 'Limburgish';
+    ln: 'Lingala';
+    lo: 'Lao';
+    lt: 'Lithuanian';
+    lu: 'Luba-Katanga';
+    lv: 'Latvian';
+    mg: 'Malagasy';
+    mh: 'Marshallese';
+    mi: 'Māori';
+    mk: 'Macedonian';
+    ml: 'Malayalam';
+    mn: 'Mongolian';
+    mr: 'Marathi';
+    ms: 'Malay';
+    mt: 'Maltese';
+    my: 'Burmese';
+    na: 'Nauru';
+    nb: 'Norwegian Bokmål';
+    nd: 'North Ndebele';
+    ne: 'Nepali';
+    ng: 'Ndonga';
+    nl: 'Dutch';
+    nn: 'Norwegian Nynorsk';
+    no: 'Norwegian';
+    nr: 'South Ndebele';
+    nv: 'Navajo';
+    ny: 'Nyanja';
+    oc: 'Occitan';
+    oj: 'Ojibwa';
+    om: 'Oromo';
+    or: 'Odia';
+    os: 'Ossetic';
+    pa: 'Punjabi';
+    pi: 'Pali';
+    pl: 'Polish';
+    ps: 'Pashto';
+    pt: 'Portuguese';
+    qu: 'Quechua';
+    rm: 'Romansh';
+    rn: 'Rundi';
+    ro: 'Romanian';
+    ru: 'Russian';
+    rw: 'Kinyarwanda';
+    sa: 'Sanskrit';
+    sc: 'Sardinian';
+    sd: 'Sindhi';
+    se: 'Northern Sami';
+    sg: 'Sango';
+    si: 'Sinhala';
+    sk: 'Slovak';
+    sl: 'Slovenian';
+    sm: 'Samoan';
+    sn: 'Shona';
+    so: 'Somali';
+    sq: 'Albanian';
+    sr: 'Serbian';
+    ss: 'Swati';
+    st: 'Southern Sotho';
+    su: 'Sundanese';
+    sv: 'Swedish';
+    sw: 'Swahili';
+    ta: 'Tamil';
+    te: 'Telugu';
+    tg: 'Tajik';
+    th: 'Thai';
+    ti: 'Tigrinya';
+    tk: 'Turkmen';
+    tl: 'Filipino';
+    tn: 'Tswana';
+    to: 'Tongan';
+    tr: 'Turkish';
+    ts: 'Tsonga';
+    tt: 'Tatar';
+    tw: 'Akan';
+    ty: 'Tahitian';
+    ug: 'Uyghur';
+    uk: 'Ukrainian';
+    ur: 'Urdu';
+    uz: 'Uzbek';
+    ve: 'Venda';
+    vi: 'Vietnamese';
+    vo: 'Volapük';
+    wa: 'Walloon';
+    wo: 'Wolof';
+    xh: 'Xhosa';
+    yi: 'Yiddish';
+    yo: 'Yoruba';
+    za: 'Zhuang';
+    zh: 'Chinese';
+    zu: 'Zulu';
+};
+
+/** The languages configured in `I18nConfiguration` or all ISO languages */
+export declare type Language = ExtractConfig<I18nConfiguration, ISOLanguage, 'languages'>;
+
+/** Create a _reactive_ translator object from the given options */
+export declare function makeTranslator(options: I18nOptions): Translator;
+
+/** Prettify our `Translations` exported type */
+declare type PrettifyTranslation<T> = {
+    [l in keyof T]: T[l];
+};
+
+/**
+ * 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.
+ */
+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.
+ *
+ * When left unconfigured, this type will be `string`.
+ */
+export declare type TranslationKey = ExtractConfig<I18nConfiguration, string, 'translationKeys'>;
+
+/**
+ * Parameters for the formatting of a translation.
+ *
+ * This type is used to pass parameters to the `t` and `tc` methods of the
+ * 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.
+ */
+export declare interface TranslationParams {
+    [key: string]: string | number;
+}
+
+/**
+ * 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.
+ */
+export declare interface Translations {
+    readonly [key: string]: Translation;
+}
+
+/**
+ * The translator interface for the application.
+ *
+ * This interface provides methods to translate messages, format numbers, and
+ * format dates and times.
+ *
+ * Configured instances can be accessed using the `useI18n()` 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. */
+    region: ISOCountry | undefined;
+    /** The `Locale` used by this translator (merges `language` and `region`) */
+    locale: 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
+     */
+    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:
+     *
+     * * `" 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
+     * * `" 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
+     *
+     * For convenience, the `{n}` message parameter will always be contextualized
+     * with the number, unless overridden in the `params` themselves.
+     */
+    tc(key: TranslationKey | Translation, n: number, params?: TranslationParams): string;
+    /**
+     * Format a number into a string according to the current language.
+     *
+     * If the `currency` parameter is set, the number will be formatted as a
+     * currency value, using the specified currency symbol.
+     */
+    n(value?: number | bigint | null | undefined, currency?: string): string;
+    /**
+     * Format a number into a string according to the current language.
+     *
+     * When `format` is provided, it will be used to configure the number format,
+     * otherwise the default `format.numberFormat` plugin option will be used.
+     */
+    n(value?: number | bigint | null | undefined, format?: Intl.NumberFormatOptions): string;
+    d: {
+        /**
+         * Format date and time according to the current language.
+         *
+         * When `style` is provided, it will be used to configure the date and time
+         * format, otherwise the default `format.dateTimeFormat` plugin option will
+         * be used.
+         */
+        (date?: DateInput, style?: DateTimeFormats['dateTimeFormat']): string;
+        /**
+         * Format the date part (without time) according to the current language.
+         *
+         * When `style` is provided, it will be used to configure the date and time
+         * format, otherwise the default `format.dateOnlyFormat` plugin option will
+         * be used.
+         */
+        date(date?: DateInput, style?: DateTimeFormats['dateOnlyFormat']): string;
+        /**
+         * Format the time part (without date) according to the current language.
+         *
+         * When `style` is provided, it will be used to configure the date and time
+         * format, otherwise the default `format.timeOnlyFormat` plugin option will
+         * be used.
+         */
+        time(date?: DateInput, style?: DateTimeFormats['timeOnlyFormat']): string;
+    };
+}
+
+/** Retrieve the translator instance from the Vue app */
+export declare function useTranslator(): Translator;
+
+export { }
+
+
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        /** Translate a message according to the current language */
+        $t: Translator['t'];
+        /**
+         * Return the (possibly parameterized) translation for the specified message
+         * in the current language, with pluralization.
+         */
+        $tc: Translator['tc'];
+        /** Format a number into a string according to the current language */
+        $n: Translator['n'];
+        /**
+         * Format date and time using the specified style (defaults to `medium`)
+         * according to the current language
+         */
+        $d: Translator['d'];
+    }
+}