@hyperse/translator
Version:
Translates messages from the given namespace by using the ICU syntax.
257 lines (239 loc) • 19.1 kB
text/typescript
import * as react from 'react';
import { ReactNode, ReactElement } from 'react';
import { IntlMessageFormat, Formats as Formats$1 } from 'intl-messageformat';
type IntlCache = {
dateTime: Record<string, Intl.DateTimeFormat>;
number: Record<string, Intl.NumberFormat>;
message: Record<string, IntlMessageFormat>;
relativeTime: Record<string, Intl.RelativeTimeFormat>;
pluralRules: Record<string, Intl.PluralRules>;
list: Record<string, Intl.ListFormat>;
displayNames: Record<string, Intl.DisplayNames>;
};
type IntlFormatters = {
getDateTimeFormat(...args: ConstructorParameters<typeof Intl.DateTimeFormat>): Intl.DateTimeFormat;
getNumberFormat(...args: ConstructorParameters<typeof Intl.NumberFormat>): Intl.NumberFormat;
getPluralRules(...args: ConstructorParameters<typeof Intl.PluralRules>): Intl.PluralRules;
getRelativeTimeFormat(...args: ConstructorParameters<typeof Intl.RelativeTimeFormat>): Intl.RelativeTimeFormat;
getListFormat(...args: ConstructorParameters<typeof Intl.ListFormat>): Intl.ListFormat;
getDisplayNames(...args: ConstructorParameters<typeof Intl.DisplayNames>): Intl.DisplayNames;
};
type MessageFormatter = (...args: ConstructorParameters<typeof IntlMessageFormat>) => IntlMessageFormat;
type Formatters = IntlFormatters & {
getMessageFormat?: MessageFormatter;
};
type AbstractIntlMessages = {
[id: string]: object | string;
};
declare enum IntlErrorCode {
MISSING_MESSAGE = "MISSING_MESSAGE",
MISSING_FORMAT = "MISSING_FORMAT",
ENVIRONMENT_FALLBACK = "ENVIRONMENT_FALLBACK",
INSUFFICIENT_PATH = "INSUFFICIENT_PATH",
INVALID_MESSAGE = "INVALID_MESSAGE",
INVALID_KEY = "INVALID_KEY",
FORMATTING_ERROR = "FORMATTING_ERROR"
}
declare class IntlError extends Error {
readonly code: IntlErrorCode;
readonly originalMessage: string | undefined;
constructor(code: IntlErrorCode, originalMessage?: string);
}
type TimeZone = 'Africa/Abidjan' | 'Africa/Accra' | 'Africa/Addis_Ababa' | 'Africa/Algiers' | 'Africa/Asmara' | 'Africa/Bamako' | 'Africa/Bangui' | 'Africa/Banjul' | 'Africa/Bissau' | 'Africa/Blantyre' | 'Africa/Brazzaville' | 'Africa/Bujumbura' | 'Africa/Cairo' | 'Africa/Casablanca' | 'Africa/Ceuta' | 'Africa/Conakry' | 'Africa/Dakar' | 'Africa/Dar_es_Salaam' | 'Africa/Djibouti' | 'Africa/Douala' | 'Africa/El_Aaiun' | 'Africa/Freetown' | 'Africa/Gaborone' | 'Africa/Harare' | 'Africa/Johannesburg' | 'Africa/Juba' | 'Africa/Kampala' | 'Africa/Khartoum' | 'Africa/Kigali' | 'Africa/Kinshasa' | 'Africa/Lagos' | 'Africa/Libreville' | 'Africa/Lome' | 'Africa/Luanda' | 'Africa/Lubumbashi' | 'Africa/Lusaka' | 'Africa/Malabo' | 'Africa/Maputo' | 'Africa/Maseru' | 'Africa/Mbabane' | 'Africa/Mogadishu' | 'Africa/Monrovia' | 'Africa/Nairobi' | 'Africa/Ndjamena' | 'Africa/Niamey' | 'Africa/Nouakchott' | 'Africa/Ouagadougou' | 'Africa/Porto-Novo' | 'Africa/Sao_Tome' | 'Africa/Tripoli' | 'Africa/Tunis' | 'Africa/Windhoek' | 'America/Adak' | 'America/Anchorage' | 'America/Anguilla' | 'America/Antigua' | 'America/Araguaina' | 'America/Argentina/Buenos_Aires' | 'America/Argentina/Catamarca' | 'America/Argentina/Cordoba' | 'America/Argentina/Jujuy' | 'America/Argentina/La_Rioja' | 'America/Argentina/Mendoza' | 'America/Argentina/Rio_Gallegos' | 'America/Argentina/Salta' | 'America/Argentina/San_Juan' | 'America/Argentina/San_Luis' | 'America/Argentina/Tucuman' | 'America/Argentina/Ushuaia' | 'America/Aruba' | 'America/Asuncion' | 'America/Atikokan' | 'America/Bahia' | 'America/Bahia_Banderas' | 'America/Barbados' | 'America/Belem' | 'America/Belize' | 'America/Blanc-Sablon' | 'America/Boa_Vista' | 'America/Bogota' | 'America/Boise' | 'America/Cambridge_Bay' | 'America/Campo_Grande' | 'America/Cancun' | 'America/Caracas' | 'America/Cayenne' | 'America/Cayman' | 'America/Chicago' | 'America/Chihuahua' | 'America/Costa_Rica' | 'America/Creston' | 'America/Cuiaba' | 'America/Curacao' | 'America/Danmarkshavn' | 'America/Dawson' | 'America/Dawson_Creek' | 'America/Denver' | 'America/Detroit' | 'America/Dominica' | 'America/Edmonton' | 'America/Eirunepe' | 'America/El_Salvador' | 'America/Fort_Nelson' | 'America/Fortaleza' | 'America/Glace_Bay' | 'America/Godthab' | 'America/Goose_Bay' | 'America/Grand_Turk' | 'America/Grenada' | 'America/Guadeloupe' | 'America/Guatemala' | 'America/Guayaquil' | 'America/Guyana' | 'America/Halifax' | 'America/Havana' | 'America/Hermosillo' | 'America/Indiana/Indianapolis' | 'America/Indiana/Knox' | 'America/Indiana/Marengo' | 'America/Indiana/Petersburg' | 'America/Indiana/Tell_City' | 'America/Indiana/Vevay' | 'America/Indiana/Vincennes' | 'America/Indiana/Winamac' | 'America/Inuvik' | 'America/Iqaluit' | 'America/Jamaica' | 'America/Juneau' | 'America/Kentucky/Louisville' | 'America/Kentucky/Monticello' | 'America/Kralendijk' | 'America/La_Paz' | 'America/Lima' | 'America/Los_Angeles' | 'America/Lower_Princes' | 'America/Maceio' | 'America/Managua' | 'America/Manaus' | 'America/Marigot' | 'America/Martinique' | 'America/Matamoros' | 'America/Mazatlan' | 'America/Menominee' | 'America/Merida' | 'America/Metlakatla' | 'America/Mexico_City' | 'America/Miquelon' | 'America/Moncton' | 'America/Monterrey' | 'America/Montevideo' | 'America/Montserrat' | 'America/Nassau' | 'America/New_York' | 'America/Nipigon' | 'America/Nome' | 'America/Noronha' | 'America/North_Dakota/Beulah' | 'America/North_Dakota/Center' | 'America/North_Dakota/New_Salem' | 'America/Ojinaga' | 'America/Panama' | 'America/Pangnirtung' | 'America/Paramaribo' | 'America/Phoenix' | 'America/Port-au-Prince' | 'America/Port_of_Spain' | 'America/Porto_Velho' | 'America/Puerto_Rico' | 'America/Punta_Arenas' | 'America/Rainy_River' | 'America/Rankin_Inlet' | 'America/Recife' | 'America/Regina' | 'America/Resolute' | 'America/Rio_Branco' | 'America/Santarem' | 'America/Santiago' | 'America/Santo_Domingo' | 'America/Sao_Paulo' | 'America/Scoresbysund' | 'America/Sitka' | 'America/St_Barthelemy' | 'America/St_Johns' | 'America/St_Kitts' | 'America/St_Lucia' | 'America/St_Thomas' | 'America/St_Vincent' | 'America/Swift_Current' | 'America/Tegucigalpa' | 'America/Thule' | 'America/Thunder_Bay' | 'America/Tijuana' | 'America/Toronto' | 'America/Tortola' | 'America/Vancouver' | 'America/Whitehorse' | 'America/Winnipeg' | 'America/Yakutat' | 'America/Yellowknife' | 'Antarctica/Casey' | 'Antarctica/Davis' | 'Antarctica/DumontDUrville' | 'Antarctica/Macquarie' | 'Antarctica/Mawson' | 'Antarctica/Palmer' | 'Antarctica/Rothera' | 'Antarctica/Syowa' | 'Antarctica/Troll' | 'Antarctica/Vostok' | 'Arctic/Longyearbyen' | 'Asia/Almaty' | 'Asia/Amman' | 'Asia/Anadyr' | 'Asia/Aqtau' | 'Asia/Aqtobe' | 'Asia/Ashgabat' | 'Asia/Atyrau' | 'Asia/Baghdad' | 'Asia/Baku' | 'Asia/Bangkok' | 'Asia/Barnaul' | 'Asia/Beirut' | 'Asia/Bishkek' | 'Asia/Brunei' | 'Asia/Chita' | 'Asia/Choibalsan' | 'Asia/Colombo' | 'Asia/Damascus' | 'Asia/Dhaka' | 'Asia/Dili' | 'Asia/Dubai' | 'Asia/Dushanbe' | 'Asia/Famagusta' | 'Asia/Gaza' | 'Asia/Hebron' | 'Asia/Ho_Chi_Minh' | 'Asia/Hong_Kong' | 'Asia/Hovd' | 'Asia/Irkutsk' | 'Asia/Jakarta' | 'Asia/Jayapura' | 'Asia/Jerusalem' | 'Asia/Kabul' | 'Asia/Kamchatka' | 'Asia/Karachi' | 'Asia/Kathmandu' | 'Asia/Khandyga' | 'Asia/Kolkata' | 'Asia/Krasnoyarsk' | 'Asia/Kuala_Lumpur' | 'Asia/Kuching' | 'Asia/Macau' | 'Asia/Magadan' | 'Asia/Makassar' | 'Asia/Manila' | 'Asia/Nicosia' | 'Asia/Novokuznetsk' | 'Asia/Novosibirsk' | 'Asia/Omsk' | 'Asia/Oral' | 'Asia/Phnom_Penh' | 'Asia/Pontianak' | 'Asia/Pyongyang' | 'Asia/Qatar' | 'Asia/Qostanay' | 'Asia/Qyzylorda' | 'Asia/Riyadh' | 'Asia/Sakhalin' | 'Asia/Samarkand' | 'Asia/Seoul' | 'Asia/Shanghai' | 'Asia/Singapore' | 'Asia/Srednekolymsk' | 'Asia/Taipei' | 'Asia/Tashkent' | 'Asia/Tbilisi' | 'Asia/Tehran' | 'Asia/Thimphu' | 'Asia/Tokyo' | 'Asia/Tomsk' | 'Asia/Ulaanbaatar' | 'Asia/Urumqi' | 'Asia/Ust-Nera' | 'Asia/Vladivostok' | 'Asia/Yakutsk' | 'Asia/Yangon' | 'Asia/Yekaterinburg' | 'Asia/Yerevan' | 'Atlantic/Azores' | 'Atlantic/Bermuda' | 'Atlantic/Canary' | 'Atlantic/Cape_Verde' | 'Atlantic/Faroe' | 'Atlantic/Madeira' | 'Atlantic/Reykjavik' | 'Atlantic/South_Georgia' | 'Atlantic/St_Helena' | 'Atlantic/Stanley' | 'Australia/Adelaide' | 'Australia/Brisbane' | 'Australia/Broken_Hill' | 'Australia/Currie' | 'Australia/Darwin' | 'Australia/Eucla' | 'Australia/Hobart' | 'Australia/Lindeman' | 'Australia/Lord_Howe' | 'Australia/Melbourne' | 'Australia/Perth' | 'Australia/Sydney' | 'Europe/Amsterdam' | 'Europe/Andorra' | 'Europe/Astrakhan' | 'Europe/Athens' | 'Europe/Belgrade' | 'Europe/Berlin' | 'Europe/Bratislava' | 'Europe/Brussels' | 'Europe/Bucharest' | 'Europe/Budapest' | 'Europe/Busingen' | 'Europe/Chisinau' | 'Europe/Copenhagen' | 'Europe/Dublin' | 'Europe/Gibraltar' | 'Europe/Guernsey' | 'Europe/Helsinki' | 'Europe/Isle_of_Man' | 'Europe/Istanbul' | 'Europe/Jersey' | 'Europe/Kaliningrad' | 'Europe/Kiev' | 'Europe/Kirov' | 'Europe/Lisbon' | 'Europe/Ljubljana' | 'Europe/London' | 'Europe/Luxembourg' | 'Europe/Madrid' | 'Europe/Malta' | 'Europe/Mariehamn' | 'Europe/Minsk' | 'Europe/Monaco' | 'Europe/Moscow' | 'Europe/Oslo' | 'Europe/Paris' | 'Europe/Podgorica' | 'Europe/Prague' | 'Europe/Riga' | 'Europe/Rome' | 'Europe/Samara' | 'Europe/San_Marino' | 'Europe/Sarajevo' | 'Europe/Saratov' | 'Europe/Simferopol' | 'Europe/Skopje' | 'Europe/Sofia' | 'Europe/Stockholm' | 'Europe/Tallinn' | 'Europe/Tirane' | 'Europe/Ulyanovsk' | 'Europe/Uzhgorod' | 'Europe/Vaduz' | 'Europe/Vatican' | 'Europe/Vienna' | 'Europe/Vilnius' | 'Europe/Volgograd' | 'Europe/Warsaw' | 'Europe/Zagreb' | 'Europe/Zaporozhye' | 'Europe/Zurich' | 'Indian/Antananarivo' | 'Indian/Chagos' | 'Indian/Christmas' | 'Indian/Cocos' | 'Indian/Comoro' | 'Indian/Kerguelen' | 'Indian/Mahe' | 'Indian/Maldives' | 'Indian/Mauritius' | 'Indian/Mayotte' | 'Indian/Reunion' | 'Pacific/Apia' | 'Pacific/Auckland' | 'Pacific/Bougainville' | 'Pacific/Chatham' | 'Pacific/Chuuk' | 'Pacific/Easter' | 'Pacific/Efate' | 'Pacific/Enderbury' | 'Pacific/Fakaofo' | 'Pacific/Fiji' | 'Pacific/Funafuti' | 'Pacific/Galapagos' | 'Pacific/Gambier' | 'Pacific/Guadalcanal' | 'Pacific/Guam' | 'Pacific/Honolulu' | 'Pacific/Kiritimati' | 'Pacific/Kosrae' | 'Pacific/Kwajalein' | 'Pacific/Majuro' | 'Pacific/Marquesas' | 'Pacific/Nauru' | 'Pacific/Niue' | 'Pacific/Norfolk' | 'Pacific/Noumea' | 'Pacific/Pago_Pago' | 'Pacific/Palau' | 'Pacific/Pitcairn' | 'Pacific/Pohnpei' | 'Pacific/Port_Moresby' | 'Pacific/Rarotonga' | 'Pacific/Tahiti' | 'Pacific/Tarawa' | 'Pacific/Tongatapu' | 'Pacific/Wake' | 'Pacific/Wallis' | 'UTC' | 'W-SU' | 'WET' | 'Zulu';
type TranslationValue = string | number | boolean | Date | null | undefined;
type RichTranslationValues = Record<string, TranslationValue | ((chunks: ReactNode) => ReactNode)>;
type IntlConfig<Messages = AbstractIntlMessages> = {
/**
* A valid Unicode locale tag (e.g. "en" or "en_GB").
*/
locale: string;
/**
* Global formats can be provided to achieve consistent
* formatting across components.
*/
formats?: Partial<Formats$1>;
/**
* A time zone as defined in [the tz database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) which will be applied when formatting dates and times. If this is absent, the user time zone will be used. You can override this by supplying an explicit time zone to `formatDateTime`.
*/
timeZone?: TimeZone;
/** This callback will be invoked when an error is encountered during
* resolving a message or formatting it. This defaults to `console.error` to
* keep your app running. You can customize the handling by taking
* `error.code` into account. */
onError?(error: IntlError): void;
/** Will be called when a message couldn't be resolved or formatting it led to
* an error. This defaults to `${namespace}.${key}` You can use this to
* customize what will be rendered in this case. */
getMessageFallback?(info: {
error: IntlError;
key: string;
namespace?: string;
}): string;
/**
* Providing this value will have two effects:
* 1. It will be used as the default for the `now` argument of
* `useFormatter().formatRelativeTime` if no explicit value is provided.
* 2. It will be returned as a static value from the `useNow` hook. Note
* however that when `updateInterval` is configured on the `useNow` hook,
* the global `now` value will only be used for the initial render, but
* afterwards the current date will be returned continuously.
*/
now?: Date;
/**
* All messages that will be available.
*/
messages?: Messages;
/**
* Global default values for translation values and rich text elements.
* Can be used for consistent usage or styling of rich text elements.
* Defaults will be overidden by locally provided values.
*/
defaultTranslationValues?: RichTranslationValues;
};
type NestedValueOf<ObjectType, Property extends string> = Property extends `${infer Key}.${infer Rest}` ? Key extends keyof ObjectType ? NestedValueOf<ObjectType[Key], Rest> : never : Property extends keyof ObjectType ? ObjectType[Property] : never;
type MessageKeys<ObjectType, Keys extends string> = {
[Property in Keys]: NestedValueOf<ObjectType, Property> extends string ? Property : never;
}[Keys];
type NamespaceKeys<ObjectType, Keys extends string> = {
[Property in Keys]: NestedValueOf<ObjectType, Property> extends string ? never : Property;
}[Keys];
type NestedKeyOf<ObjectType> = ObjectType extends object ? {
[Key in keyof ObjectType]: `${Key & string}` | `${Key & string}.${NestedKeyOf<ObjectType[Key]>}`;
}[keyof ObjectType] : never;
/**
* Translates messages from the given namespace by using the ICU syntax.
* See https://formatjs.io/docs/core-concepts/icu-syntax.
*
* If no namespace is provided, all available messages are returned.
* The namespace can also indicate nesting by using a dot
* (e.g. `namespace.Component`).
*/
declare function createTranslator<IntlMessages extends AbstractIntlMessages, NestedKey extends NamespaceKeys<IntlMessages, NestedKeyOf<IntlMessages>> = never>({ _cache, _formatters, messages, namespace, onError, getMessageFallback, ...rest }: Omit<IntlConfig<IntlMessages>, 'defaultTranslationValues' | 'messages'> & {
messages: IntlMessages;
namespace?: NestedKey;
/** @private */
_formatters?: Formatters;
/** @private */
_cache?: IntlCache;
}): {
<TargetKey extends MessageKeys<NestedValueOf<{
'!': IntlMessages;
}, [
NestedKey
] extends [never] ? '!' : `!.${NestedKey}`>, NestedKeyOf<NestedValueOf<{
'!': IntlMessages;
}, [
NestedKey
] extends [never] ? '!' : `!.${NestedKey}`>>>>(key: TargetKey, values?: RichTranslationValues, formats?: Partial<Formats$1>): string;
rich<TargetKey extends MessageKeys<NestedValueOf<{
'!': IntlMessages;
}, [
NestedKey
] extends [never] ? '!' : `!.${NestedKey}`>, NestedKeyOf<NestedValueOf<{
'!': IntlMessages;
}, [
NestedKey
] extends [never] ? '!' : `!.${NestedKey}`>>>>(key: TargetKey, values?: RichTranslationValues, formats?: Partial<Formats$1>): string | ReactElement | ReactNode[];
};
/**
* https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat
*/
type DateTimeFormatOptions = Intl.DateTimeFormatOptions & {
/**
* Examples:
* - numeric: "2021"
* - 2-digit: "21"
*/
year?: 'numeric' | '2-digit';
/** Examples:
* - numeric: "3"
* - 2-digit: "03"
* - long: "March"
* - short: "Mar"
* - narrow: "M"
*/
month?: 'numeric' | '2-digit' | 'long' | 'short' | 'narrow';
/** Examples:
* - numeric: "2"
* - 2-digit: "02"
*/
day?: 'numeric' | '2-digit';
/** Examples:
* - numeric: "2"
* - 2-digit: "02"
*/
hour?: 'numeric' | '2-digit';
/** Examples:
* - numeric: "2"
* - 2-digit: "02"
*/
minute?: 'numeric' | '2-digit';
/** Examples:
* - numeric: "2"
* - 2-digit: "02"
*/
second?: 'numeric' | '2-digit';
/** Examples:
* - long: "Thursday"
* - short: "Thu"
* - narrow: "T"
*/
weekday?: 'long' | 'short' | 'narrow';
/** Examples:
* - long: "Anno Domini"
* - short: "AD", narrow "A"
*/
era?: 'long' | 'short' | 'narrow';
/** If this is set to `true`, a 12-hour am/pm format is used. Otherwise a 24-hour time.
*
*/
hour12?: boolean;
/** Examples:
* - long: "Pacific Daylight Time"
* - short: "PDT"
*/
timeZoneName?: 'long' | 'short';
/**
* One of the [database names from the TZ database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List).
*/
timeZone?: TimeZone;
localeMatcher?: 'best fit' | 'lookup';
formatMatcher?: 'best fit' | 'basic';
dateStyle?: 'full' | 'long' | 'medium' | 'short';
timeStyle?: 'full' | 'long' | 'medium' | 'short';
calendar?: 'buddhist' | 'chinese' | 'coptic' | 'ethiopia' | 'ethiopic' | 'gregory' | 'hebrew' | 'indian' | 'islamic' | 'iso8601' | 'japanese' | 'persian' | 'roc';
dayPeriod?: 'narrow' | 'short' | 'long';
numberingSystem?: 'arab' | 'arabext' | 'bali' | 'beng' | 'deva' | 'fullwide' | 'gujr' | 'guru' | 'hanidec' | 'khmr' | 'knda' | 'laoo' | 'latn' | 'limb' | 'mlym' | 'mong' | 'mymr' | 'orya' | 'tamldec' | 'telu' | 'thai' | 'tibt';
hourCycle?: 'h11' | 'h12' | 'h23' | 'h24';
};
type NumberFormatOptions = Formats$1['number'][string];
type Formats = {
number: Record<string, NumberFormatOptions>;
dateTime: Record<string, DateTimeFormatOptions>;
list: Record<string, Intl.ListFormatOptions>;
};
type RelativeTimeFormatOptions = {
now?: number | Date;
unit?: Intl.RelativeTimeFormatUnit;
numberingSystem?: string;
style?: Intl.RelativeTimeFormatStyle;
};
type Props = {
locale: string;
timeZone?: TimeZone;
onError?(error: IntlError): void;
formats?: Partial<Formats>;
now?: Date;
/** @private */
_formatters?: Formatters;
/** @private */
_cache?: IntlCache;
};
declare function createFormatter({ _cache: cache, _formatters: formatters, formats, locale, now: globalNow, onError, timeZone: globalTimeZone, }: Props): {
dateTime: (value: Date | number, formatOrOptions?: string | DateTimeFormatOptions) => string;
number: (value: number | bigint, formatOrOptions?: string | NumberFormatOptions) => string;
relativeTime: (date: number | Date, nowOrOptions?: RelativeTimeFormatOptions["now"] | RelativeTimeFormatOptions) => string;
list: <Value extends string | ReactElement<unknown, string | react.JSXElementConstructor<any>>>(value: Iterable<Value>, formatOrOptions?: string | Intl.ListFormatOptions) => Value extends string ? string : Iterable<ReactElement>;
dateTimeRange: (start: Date | number, end: Date | number, formatOrOptions?: string | DateTimeFormatOptions) => string;
};
export { createFormatter, createTranslator };