@itwin/core-common
Version:
iTwin.js components common to frontend and backend
108 lines • 4.63 kB
TypeScript
/** @packageDocumentation
* @module Localization
*/
/** Options for Localization
* @public
*/
export interface TranslationOptions {
/** for interpolation values */
[key: string]: any;
/**
* defaultValue to return if a translation was not found
*/
defaultValue?: any;
/**
* count value used for plurals
*/
count?: number;
/**
* used for contexts (eg. male\female)
*/
context?: any;
/**
* override languages to use
*/
lngs?: string[];
/**
* override language to lookup key if not found see fallbacks for details
*/
fallbackLng?: string;
}
/** The interface defining the localization requirements of [IModelApp]($frontend).
* @public
* @extensions
*/
export interface Localization {
/** This method must be called and awaited before using an instance of Localization.
* @param namespaces an array of namespaces to load. There must be at least one namespace, and it
* becomes the default namespace.
* @note IModelApp.startup calls this internally, so you should not call this method directly
* except for Localization instances outside of IModelApp (e.g., for tests.)
*/
initialize(namespaces: string[]): Promise<void>;
/** Return the translated value of a key.
* @param key - the key that matches a property in the JSON localization file.
* @note The key includes the namespace, which identifies the particular localization file that contains the property,
* followed by a colon, followed by the property in the JSON file.
* For example:
* ``` ts
* const dataString: string = IModelApp.localization.getLocalizedString("iModelJs:BackgroundMap.BingDataAttribution");
* ```
* assigns to dataString the string with property BackgroundMap.BingDataAttribution from the iModelJs.json localization file.
* @returns The string corresponding to the first key that resolves.
* @throws Error if no keys resolve to a string.
*/
getLocalizedString(key: string | string[], options?: TranslationOptions): string;
/** get the English string for a key. */
getEnglishString(namespace: string, key: string | string[], options?: TranslationOptions): string;
/** Replace all instances of `%{key}` within a string with the translations of those keys.
* For example:
* ``` ts
* "MyKeys": {
* "Key1": "First value",
* "Key2": "Second value"
* }
* ```
*
* ``` ts
* getLocalizedKeys("string with %{MyKeys.Key1} followed by %{MyKeys.Key2}!"") // returns "string with First Value followed by Second Value!"
* ```
*/
getLocalizedKeys(inputString: string): string;
/** Register a new Namespace and return a Promise that is fulfilled when the content is loaded.
* If the namespace is already registered, its Promise will be returned.
* @param namespace - the name of the namespace.
* @note - The registerNamespace method starts fetching the appropriate version of the JSON localization file from the server,
* based on the current locale. To make sure that fetch is complete before performing translations from this namespace, await
* fulfillment of returned Promise.
* @see [Localization in iTwin.js]($docs/learning/frontend/Localization.md)
*/
registerNamespace(namespace: string): Promise<void>;
/** Unregister a namespace.
* @param namespace - the name of the namespace.
*/
unregisterNamespace(namespace: string): void;
/** @internal */
getNamespacePromise(name: string): Promise<void> | undefined;
/** Get the list of available languages for translations */
getLanguageList(): readonly string[];
/** Change the language for translations. This overrides the language from the browser, for tests.
* @param language - the language to change to.
*/
changeLanguage(language: string): Promise<void>;
}
/** An empty [[Localization]] used if one is not provided to [IModelApp]($frontend). Does not perform localizations (merely returns the key.)
* @public
*/
export declare class EmptyLocalization implements Localization {
initialize(): Promise<void>;
getLocalizedString(key: string | string[]): string;
getEnglishString(_namespace: string, key: string | string[]): string;
getLocalizedKeys(inputString: string): string;
registerNamespace(): Promise<void>;
unregisterNamespace(): void;
getNamespacePromise(): Promise<void> | undefined;
getLanguageList(): readonly string[];
changeLanguage(): Promise<void>;
}
//# sourceMappingURL=Localization.d.ts.map