UNPKG

2.56 kBTypeScriptView Raw
1import { MessageId, TargetMessage } from './utils';
2/**
3 * Load translations for use by `$localize`, if doing runtime translation.
4 *
5 * If the `$localize` tagged strings are not going to be replaced at compiled time, it is possible
6 * to load a set of translations that will be applied to the `$localize` tagged strings at runtime,
7 * in the browser.
8 *
9 * Loading a new translation will overwrite a previous translation if it has the same `MessageId`.
10 *
11 * Note that `$localize` messages are only processed once, when the tagged string is first
12 * encountered, and does not provide dynamic language changing without refreshing the browser.
13 * Loading new translations later in the application life-cycle will not change the translated text
14 * of messages that have already been translated.
15 *
16 * The message IDs and translations are in the same format as that rendered to "simple JSON"
17 * translation files when extracting messages. In particular, placeholders in messages are rendered
18 * using the `{$PLACEHOLDER_NAME}` syntax. For example the message from the following template:
19 *
20 * ```html
21 * <div i18n>pre<span>inner-pre<b>bold</b>inner-post</span>post</div>
22 * ```
23 *
24 * would have the following form in the `translations` map:
25 *
26 * ```ts
27 * {
28 * "2932901491976224757":
29 * "pre{$START_TAG_SPAN}inner-pre{$START_BOLD_TEXT}bold{$CLOSE_BOLD_TEXT}inner-post{$CLOSE_TAG_SPAN}post"
30 * }
31 * ```
32 *
33 * @param translations A map from message ID to translated message.
34 *
35 * These messages are processed and added to a lookup based on their `MessageId`.
36 *
37 * @see `clearTranslations()` for removing translations loaded using this function.
38 * @see `$localize` for tagging messages as needing to be translated.
39 * @publicApi
40 */
41export declare function loadTranslations(translations: Record<MessageId, TargetMessage>): void;
42/**
43 * Remove all translations for `$localize`, if doing runtime translation.
44 *
45 * All translations that had been loading into memory using `loadTranslations()` will be removed.
46 *
47 * @see `loadTranslations()` for loading translations at runtime.
48 * @see `$localize` for tagging messages as needing to be translated.
49 *
50 * @publicApi
51 */
52export declare function clearTranslations(): void;
53/**
54 * Translate the text of the given message, using the loaded translations.
55 *
56 * This function may reorder (or remove) substitutions as indicated in the matching translation.
57 */
58export declare function translate(messageParts: TemplateStringsArray, substitutions: readonly any[]): [
59 TemplateStringsArray,
60 readonly any[]
61];