@vaadin/hilla-react-i18n/index.d.ts

Hilla I18n utils for React

import { type ReadonlySignal } from "@vaadin/hilla-react-signals";
import type { I18nOptions } from "./types.js";
declare const keyLiteralMarker: unique symbol;
/**
* A type for translation keys. It is a string with a special marker.
*/
export type I18nKey = string & {
	[keyLiteralMarker]: unknown
};
export declare class I18n {
	#private;
	constructor();
	/**
	* Returns a signal indicating whether the I18n instance has been initialized.
	* The instance is considered initialized after `configure` has been called
	* and translations for the initial language have been loaded. Can be used to
	* show a placeholder or loading indicator until the translations are ready.
	*
	* Subscribers to this signal will be notified when initialization is complete
	* and translations are ready to be used.
	*/
	get initialized(): ReadonlySignal<boolean>;
	/**
	* Returns a signal with the currently configured language.
	*
	* Subscribers to this signal will be notified when the language has changed
	* and new translations have been loaded.
	*/
	get language(): ReadonlySignal<string | undefined>;
	/**
	* Returns a signal with the resolved language. The resolved language is the
	* language that was actually used to load translations. It may differ from
	* the configured language if there are no translations available for the
	* configured language. For example, when setting the language to "de-DE" but
	* translations are only available for "de", the resolved language will be
	* "de".
	*/
	get resolvedLanguage(): ReadonlySignal<string | undefined>;
	/**
	* Initializes the I18n instance. This method should be called once to load
	* translations for the initial language. The `translate` API will not return
	* properly translated strings until the initializations has completed.
	*
	* The initialization runs asynchronously as translations are loaded from the
	* backend. The method returns a promise that resolves when the translations
	* have been loaded, after which the `translate` API can safely be used.
	*
	* The initial language is determined as follows:
	* 1. If a user opens the app for the first time, the browser language is used.
	* 2. If the language has been changed in a previous usage of the app using
	* `setLanguage`, the last used language is used. The last used language is
	* automatically stored in local storage.
	*
	* Alternatively, the initial language can be explicitly configured using the
	* `language` option. The language should be a valid IETF BCP 47 language tag,
	* such as `en` or `en-US`.
	*
	* @param options - Optional options object to specify the initial language.
	*/
	configure(options?: I18nOptions): Promise<void>;
	/**
	* Changes the current language and loads translations for the new language.
	* Components using the `translate` API will automatically re-render, and
	* subscribers to the `language` signal will be notified, when the new
	* translations have been loaded.
	*
	* The language should be a valid IETF BCP 47 language tag, such as `en` or
	* `en-US`.
	*
	* If there is no translation file for that specific language tag, the backend
	* will try to load the translation file for the parent language tag. For
	* example, if there is no translation file for `en-US`, the backend will try
	* to load the translation file for `en`. Otherwise, it will fall back to the
	* default translation file `translations.properties`.
	*
	* Changing the language is an asynchronous operation. The method returns a
	* promise that resolves when the translations for the new language have been
	* loaded.
	*
	* @param newLanguage - a valid IETF BCP 47 language tag, such as `en` or `en-US`
	*/
	setLanguage(newLanguage: string): Promise<void>;
	private requestKeys;
	private updateLanguage;
	/**
	* Reloads all translations for the current language. This method should only
	* be used for HMR in development mode.
	*/
	private reloadTranslations;
	/**
	* Returns a translated string for the given translation key. The key should
	* match a key in the loaded translations. If no translation is found for the
	* key, the key itself is returned.
	*
	* Translations may contain placeholders, following the ICU MessageFormat
	* syntax. They can be replaced by passing a `params` object with placeholder
	* values, where keys correspond to the placeholder names and values are the
	* replacement value. Values should be basic types such as strings, numbers,
	* or dates that match the placeholder format configured in the translation
	* string. For example, when using a placeholder `{count, number}`, the value
	* should be a number, when using `{date, date}`, the value should be a Date
	* object, and so on.
	*
	* This method internally accesses a signal, meaning that React components
	* that use it will automatically re-render when translations change.
	* Likewise, signal effects automatically subscribe to translation changes
	* when calling this method.
	*
	* @param key - The key to translate
	* @param params - Optional object with placeholder values
	*/
	translate(key: I18nKey, params?: Record<string, unknown>): string;
	/**
	* Creates a computed signal with translated string for to the given key.
	* This method uses dynamic loading and does not guarantee immediate
	* availability of the translation.
	*
	* If the translation for the given key has not been loaded yet at the time
	* of the call, loads the translation for the key and updates the returned
	* signal value.
	*
	* When given an `undefined` key, returns empty string signal value.
	*
	* @param key - The translation key to translate
	* @param params - Optional object with placeholder values
	*/
	translateDynamic(key: string | undefined, params?: Record<string, unknown>): ReadonlySignal<string>;
	private handleMissingTranslation;
}
/**
* The global I18n instance that is used to initialize translations, change the
* current language, and translate strings.
*/
declare const i18n: I18n;
/**
* A tagged template literal function to create translation keys.
* The {@link translate} function requires using this tag.
* E.g.:
*   translate(key`my.translation.key`)
*/
declare function keyTag(strings: readonly string[], ..._values: never[]): I18nKey;
/**
* Returns a translated string for the given translation key. The key should
* match a key in the loaded translations. If no translation is found for the
* key, a modified version of the key is returned to indicate that the translation
* is missing.
*
* Translations may contain placeholders, following the ICU MessageFormat
* syntax. They can be replaced by passing a `params` object with placeholder
* values, where keys correspond to the placeholder names and values are the
* replacement value. Values should be basic types such as strings, numbers,
* or dates that match the placeholder format configured in the translation
* string. For example, when using a placeholder `{count, number}`, the value
* should be a number, when using `{date, date}`, the value should be a Date
* object, and so on.
*
* This method internally accesses a signal, meaning that React components
* that use it will automatically re-render when translations change.
* Likewise, signal effects automatically subscribe to translation changes
* when calling this method.
*
* This function is a shorthand for `i18n.translate` of the global I18n instance.
*
* @param key - The translation key to translate
* @param params - Optional object with placeholder values
*/
export declare function translate(key: I18nKey, params?: Record<string, unknown>): string;
export { i18n, keyTag as key };