1 | /**
|
2 | * @license Angular v14.1.3
|
3 | * (c) 2010-2022 Google LLC. https://angular.io/
|
4 | * License: MIT
|
5 | */
|
6 |
|
7 |
|
8 | import { computeMsgId as ɵcomputeMsgId } from '@angular/compiler';
|
9 |
|
10 | /**
|
11 | * Declares a copy of the `AbsoluteFsPath` branded type in `@angular/compiler-cli` to avoid an
|
12 | * import into `@angular/compiler-cli`. The compiler-cli's declaration files are not necessarily
|
13 | * compatible with web environments that use `@angular/localize`, and would inadvertently include
|
14 | * `typescript` declaration files in any compilation unit that uses `@angular/localize` (which
|
15 | * increases parsing time and memory usage during builds) using a default import that only
|
16 | * type-checks when `allowSyntheticDefaultImports` is enabled.
|
17 | *
|
18 | * @see https://github.com/angular/angular/issues/45179
|
19 | */
|
20 | declare type AbsoluteFsPathLocalizeCopy = string & {
|
21 | _brand: 'AbsoluteFsPath';
|
22 | };
|
23 |
|
24 | /**
|
25 | * Remove all translations for `$localize`, if doing runtime translation.
|
26 | *
|
27 | * All translations that had been loading into memory using `loadTranslations()` will be removed.
|
28 | *
|
29 | * @see `loadTranslations()` for loading translations at runtime.
|
30 | * @see `$localize` for tagging messages as needing to be translated.
|
31 | *
|
32 | * @publicApi
|
33 | */
|
34 | export declare function clearTranslations(): void;
|
35 |
|
36 | /**
|
37 | * Load translations for use by `$localize`, if doing runtime translation.
|
38 | *
|
39 | * If the `$localize` tagged strings are not going to be replaced at compiled time, it is possible
|
40 | * to load a set of translations that will be applied to the `$localize` tagged strings at runtime,
|
41 | * in the browser.
|
42 | *
|
43 | * Loading a new translation will overwrite a previous translation if it has the same `MessageId`.
|
44 | *
|
45 | * Note that `$localize` messages are only processed once, when the tagged string is first
|
46 | * encountered, and does not provide dynamic language changing without refreshing the browser.
|
47 | * Loading new translations later in the application life-cycle will not change the translated text
|
48 | * of messages that have already been translated.
|
49 | *
|
50 | * The message IDs and translations are in the same format as that rendered to "simple JSON"
|
51 | * translation files when extracting messages. In particular, placeholders in messages are rendered
|
52 | * using the `{$PLACEHOLDER_NAME}` syntax. For example the message from the following template:
|
53 | *
|
54 | * ```html
|
55 | * <div i18n>pre<span>inner-pre<b>bold</b>inner-post</span>post</div>
|
56 | * ```
|
57 | *
|
58 | * would have the following form in the `translations` map:
|
59 | *
|
60 | * ```ts
|
61 | * {
|
62 | * "2932901491976224757":
|
63 | * "pre{$START_TAG_SPAN}inner-pre{$START_BOLD_TEXT}bold{$CLOSE_BOLD_TEXT}inner-post{$CLOSE_TAG_SPAN}post"
|
64 | * }
|
65 | * ```
|
66 | *
|
67 | * @param translations A map from message ID to translated message.
|
68 | *
|
69 | * These messages are processed and added to a lookup based on their `MessageId`.
|
70 | *
|
71 | * @see `clearTranslations()` for removing translations loaded using this function.
|
72 | * @see `$localize` for tagging messages as needing to be translated.
|
73 | * @publicApi
|
74 | */
|
75 | export declare function loadTranslations(translations: Record<MessageId, TargetMessage>): void;
|
76 |
|
77 | /**
|
78 | * A string that uniquely identifies a message, to be used for matching translations.
|
79 | */
|
80 | export declare type MessageId = string;
|
81 |
|
82 | /**
|
83 | * Additional information that can be associated with a message.
|
84 | */
|
85 | declare interface MessageMetadata {
|
86 | /**
|
87 | * A human readable rendering of the message
|
88 | */
|
89 | text: string;
|
90 | /**
|
91 | * Legacy message ids, if provided.
|
92 | *
|
93 | * In legacy message formats the message id can only be computed directly from the original
|
94 | * template source.
|
95 | *
|
96 | * Since this information is not available in `$localize` calls, the legacy message ids may be
|
97 | * attached by the compiler to the `$localize` metablock so it can be used if needed at the point
|
98 | * of translation if the translations are encoded using the legacy message id.
|
99 | */
|
100 | legacyIds?: string[];
|
101 | /**
|
102 | * The id of the `message` if a custom one was specified explicitly.
|
103 | *
|
104 | * This id overrides any computed or legacy ids.
|
105 | */
|
106 | customId?: string;
|
107 | /**
|
108 | * The meaning of the `message`, used to distinguish identical `messageString`s.
|
109 | */
|
110 | meaning?: string;
|
111 | /**
|
112 | * The description of the `message`, used to aid translation.
|
113 | */
|
114 | description?: string;
|
115 | /**
|
116 | * The location of the message in the source.
|
117 | */
|
118 | location?: ɵSourceLocation;
|
119 | }
|
120 |
|
121 | /**
|
122 | * A string containing a translation target message.
|
123 | *
|
124 | * I.E. the message that indicates what will be translated to.
|
125 | *
|
126 | * Uses `{$placeholder-name}` to indicate a placeholder.
|
127 | */
|
128 | export declare type TargetMessage = string;
|
129 |
|
130 | /**
|
131 | * Tag a template literal string for localization.
|
132 | *
|
133 | * For example:
|
134 | *
|
135 | * ```ts
|
136 | * $localize `some string to localize`
|
137 | * ```
|
138 | *
|
139 | * **Providing meaning, description and id**
|
140 | *
|
141 | * You can optionally specify one or more of `meaning`, `description` and `id` for a localized
|
142 | * string by pre-pending it with a colon delimited block of the form:
|
143 | *
|
144 | * ```ts
|
145 | * $localize`:meaning|description@@id:source message text`;
|
146 | *
|
147 | * $localize`:meaning|:source message text`;
|
148 | * $localize`:description:source message text`;
|
149 | * $localize`:@@id:source message text`;
|
150 | * ```
|
151 | *
|
152 | * This format is the same as that used for `i18n` markers in Angular templates. See the
|
153 | * [Angular i18n guide](guide/i18n-common-prepare#mark-text-in-component-template).
|
154 | *
|
155 | * **Naming placeholders**
|
156 | *
|
157 | * If the template literal string contains expressions, then the expressions will be automatically
|
158 | * associated with placeholder names for you.
|
159 | *
|
160 | * For example:
|
161 | *
|
162 | * ```ts
|
163 | * $localize `Hi ${name}! There are ${items.length} items.`;
|
164 | * ```
|
165 | *
|
166 | * will generate a message-source of `Hi {$PH}! There are {$PH_1} items`.
|
167 | *
|
168 | * The recommended practice is to name the placeholder associated with each expression though.
|
169 | *
|
170 | * Do this by providing the placeholder name wrapped in `:` characters directly after the
|
171 | * expression. These placeholder names are stripped out of the rendered localized string.
|
172 | *
|
173 | * For example, to name the `items.length` expression placeholder `itemCount` you write:
|
174 | *
|
175 | * ```ts
|
176 | * $localize `There are ${items.length}:itemCount: items`;
|
177 | * ```
|
178 | *
|
179 | * **Escaping colon markers**
|
180 | *
|
181 | * If you need to use a `:` character directly at the start of a tagged string that has no
|
182 | * metadata block, or directly after a substitution expression that has no name you must escape
|
183 | * the `:` by preceding it with a backslash:
|
184 | *
|
185 | * For example:
|
186 | *
|
187 | * ```ts
|
188 | * // message has a metadata block so no need to escape colon
|
189 | * $localize `:some description::this message starts with a colon (:)`;
|
190 | * // no metadata block so the colon must be escaped
|
191 | * $localize `\:this message starts with a colon (:)`;
|
192 | * ```
|
193 | *
|
194 | * ```ts
|
195 | * // named substitution so no need to escape colon
|
196 | * $localize `${label}:label:: ${}`
|
197 | * // anonymous substitution so colon must be escaped
|
198 | * $localize `${label}\: ${}`
|
199 | * ```
|
200 | *
|
201 | * **Processing localized strings:**
|
202 | *
|
203 | * There are three scenarios:
|
204 | *
|
205 | * * **compile-time inlining**: the `$localize` tag is transformed at compile time by a
|
206 | * transpiler, removing the tag and replacing the template literal string with a translated
|
207 | * literal string from a collection of translations provided to the transpilation tool.
|
208 | *
|
209 | * * **run-time evaluation**: the `$localize` tag is a run-time function that replaces and
|
210 | * reorders the parts (static strings and expressions) of the template literal string with strings
|
211 | * from a collection of translations loaded at run-time.
|
212 | *
|
213 | * * **pass-through evaluation**: the `$localize` tag is a run-time function that simply evaluates
|
214 | * the original template literal string without applying any translations to the parts. This
|
215 | * version is used during development or where there is no need to translate the localized
|
216 | * template literals.
|
217 | *
|
218 | * @param messageParts a collection of the static parts of the template string.
|
219 | * @param expressions a collection of the values of each placeholder in the template string.
|
220 | * @returns the translated string, with the `messageParts` and `expressions` interleaved together.
|
221 | *
|
222 | * @globalApi
|
223 | * @publicApi
|
224 | */
|
225 | export declare const ɵ$localize: ɵLocalizeFn;
|
226 |
|
227 | export declare const ɵ_global: any;
|
228 |
|
229 | export { ɵcomputeMsgId }
|
230 |
|
231 | /**
|
232 | * Find the end of a "marked block" indicated by the first non-escaped colon.
|
233 | *
|
234 | * @param cooked The cooked string (where escaped chars have been processed)
|
235 | * @param raw The raw string (where escape sequences are still in place)
|
236 | *
|
237 | * @returns the index of the end of block marker
|
238 | * @throws an error if the block is unterminated
|
239 | */
|
240 | export declare function ɵfindEndOfBlock(cooked: string, raw: string): number;
|
241 |
|
242 | export declare function ɵisMissingTranslationError(e: any): e is ɵMissingTranslationError;
|
243 |
|
244 |
|
245 | /** @nodoc */
|
246 | export declare interface ɵLocalizeFn {
|
247 | (messageParts: TemplateStringsArray, ...expressions: readonly any[]): string;
|
248 | /**
|
249 | * A function that converts an input "message with expressions" into a translated "message with
|
250 | * expressions".
|
251 | *
|
252 | * The conversion may be done in place, modifying the array passed to the function, so
|
253 | * don't assume that this has no side-effects.
|
254 | *
|
255 | * The expressions must be passed in since it might be they need to be reordered for
|
256 | * different translations.
|
257 | */
|
258 | translate?: ɵTranslateFn;
|
259 | /**
|
260 | * The current locale of the translated messages.
|
261 | *
|
262 | * The compile-time translation inliner is able to replace the following code:
|
263 | *
|
264 | * ```
|
265 | * typeof $localize !== "undefined" && $localize.locale
|
266 | * ```
|
267 | *
|
268 | * with a string literal of the current locale. E.g.
|
269 | *
|
270 | * ```
|
271 | * "fr"
|
272 | * ```
|
273 | */
|
274 | locale?: string;
|
275 | }
|
276 |
|
277 | /**
|
278 | * Create a `ParsedTranslation` from a set of `messageParts` and `placeholderNames`.
|
279 | *
|
280 | * @param messageParts The message parts to appear in the ParsedTranslation.
|
281 | * @param placeholderNames The names of the placeholders to intersperse between the `messageParts`.
|
282 | */
|
283 | export declare function ɵmakeParsedTranslation(messageParts: string[], placeholderNames?: string[]): ɵParsedTranslation;
|
284 |
|
285 | /**
|
286 | * Create the specialized array that is passed to tagged-string tag functions.
|
287 | *
|
288 | * @param cooked The message parts with their escape codes processed.
|
289 | * @param raw The message parts with their escaped codes as-is.
|
290 | */
|
291 | export declare function ɵmakeTemplateObject(cooked: string[], raw: string[]): TemplateStringsArray;
|
292 |
|
293 | export declare class ɵMissingTranslationError extends Error {
|
294 | readonly parsedMessage: ɵParsedMessage;
|
295 | private readonly type;
|
296 | constructor(parsedMessage: ɵParsedMessage);
|
297 | }
|
298 |
|
299 | /**
|
300 | * Information parsed from a `$localize` tagged string that is used to translate it.
|
301 | *
|
302 | * For example:
|
303 | *
|
304 | * ```
|
305 | * const name = 'Jo Bloggs';
|
306 | * $localize`Hello ${name}:title@`;
:! |
307 | * ```
|
308 | *
|
309 | * May be parsed into:
|
310 | *
|
311 | * ```
|
312 | * {
|
313 | * id: '6998194507597730591',
|
314 | * substitutions: { title: 'Jo Bloggs' },
|
315 | * messageString: 'Hello {$title}!',
|
316 | * placeholderNames: ['title'],
|
317 | * associatedMessageIds: { title: 'ID' },
|
318 | * }
|
319 | * ```
|
320 | */
|
321 | export declare interface ɵParsedMessage extends MessageMetadata {
|
322 | /**
|
323 | * The key used to look up the appropriate translation target.
|
324 | */
|
325 | id: MessageId;
|
326 | /**
|
327 | * A mapping of placeholder names to substitution values.
|
328 | */
|
329 | substitutions: Record<string, any>;
|
330 | /**
|
331 | * An optional mapping of placeholder names to associated MessageIds.
|
332 | * This can be used to match ICU placeholders to the message that contains the ICU.
|
333 | */
|
334 | associatedMessageIds?: Record<string, MessageId>;
|
335 | /**
|
336 | * An optional mapping of placeholder names to source locations
|
337 | */
|
338 | substitutionLocations?: Record<string, ɵSourceLocation | undefined>;
|
339 | /**
|
340 | * The static parts of the message.
|
341 | */
|
342 | messageParts: string[];
|
343 | /**
|
344 | * An optional mapping of message parts to source locations
|
345 | */
|
346 | messagePartLocations?: (ɵSourceLocation | undefined)[];
|
347 | /**
|
348 | * The names of the placeholders that will be replaced with substitutions.
|
349 | */
|
350 | placeholderNames: string[];
|
351 | }
|
352 |
|
353 | /**
|
354 | * A translation message that has been processed to extract the message parts and placeholders.
|
355 | */
|
356 | export declare interface ɵParsedTranslation extends MessageMetadata {
|
357 | messageParts: TemplateStringsArray;
|
358 | placeholderNames: string[];
|
359 | }
|
360 |
|
361 | /**
|
362 | * The internal structure used by the runtime localization to translate messages.
|
363 | */
|
364 | export declare type ɵParsedTranslations = Record<MessageId, ɵParsedTranslation>;
|
365 |
|
366 | /**
|
367 | * Parse a `$localize` tagged string into a structure that can be used for translation or
|
368 | * extraction.
|
369 | *
|
370 | * See `ParsedMessage` for an example.
|
371 | */
|
372 | export declare function ɵparseMessage(messageParts: TemplateStringsArray, expressions?: readonly any[], location?: ɵSourceLocation, messagePartLocations?: (ɵSourceLocation | undefined)[], expressionLocations?: (ɵSourceLocation | undefined)[]): ɵParsedMessage;
|
373 |
|
374 | /**
|
375 | * Parse the given message part (`cooked` + `raw`) to extract the message metadata from the text.
|
376 | *
|
377 | * If the message part has a metadata block this function will extract the `meaning`,
|
378 | * `description`, `customId` and `legacyId` (if provided) from the block. These metadata properties
|
379 | * are serialized in the string delimited by `|`, `@@` and `␟` respectively.
|
380 | *
|
381 | * (Note that `␟` is the `LEGACY_ID_INDICATOR` - see `constants.ts`.)
|
382 | *
|
383 | * For example:
|
384 | *
|
385 | * ```ts
|
386 | * `:meaning|description@@custom-id:`
|
387 | * `:meaning|@@custom-id:`
|
388 | * `:meaning|description:`
|
389 | * `:description@@custom-id:`
|
390 | * `:meaning|:`
|
391 | * `:description:`
|
392 | * `:@@custom-id:`
|
393 | * `:meaning|description@@custom-id␟legacy-id-1␟legacy-id-2:`
|
394 | * ```
|
395 | *
|
396 | * @param cooked The cooked version of the message part to parse.
|
397 | * @param raw The raw version of the message part to parse.
|
398 | * @returns A object containing any metadata that was parsed from the message part.
|
399 | */
|
400 | export declare function ɵparseMetadata(cooked: string, raw: string): MessageMetadata;
|
401 |
|
402 | /**
|
403 | * Parse the `messageParts` and `placeholderNames` out of a target `message`.
|
404 | *
|
405 | * Used by `loadTranslations()` to convert target message strings into a structure that is more
|
406 | * appropriate for doing translation.
|
407 | *
|
408 | * @param message the message to be parsed.
|
409 | */
|
410 | export declare function ɵparseTranslation(messageString: TargetMessage): ɵParsedTranslation;
|
411 |
|
412 | /**
|
413 | * The location of the message in the source file.
|
414 | *
|
415 | * The `line` and `column` values for the `start` and `end` properties are zero-based.
|
416 | */
|
417 | export declare interface ɵSourceLocation {
|
418 | start: {
|
419 | line: number;
|
420 | column: number;
|
421 | };
|
422 | end: {
|
423 | line: number;
|
424 | column: number;
|
425 | };
|
426 | file: AbsoluteFsPathLocalizeCopy;
|
427 | text?: string;
|
428 | }
|
429 |
|
430 | /**
|
431 | * A string containing a translation source message.
|
432 | *
|
433 | * I.E. the message that indicates what will be translated from.
|
434 | *
|
435 | * Uses `{$placeholder-name}` to indicate a placeholder.
|
436 | */
|
437 | export declare type ɵSourceMessage = string;
|
438 |
|
439 | /**
|
440 | * Split a message part (`cooked` + `raw`) into an optional delimited "block" off the front and the
|
441 | * rest of the text of the message part.
|
442 | *
|
443 | * Blocks appear at the start of message parts. They are delimited by a colon `:` character at the
|
444 | * start and end of the block.
|
445 | *
|
446 | * If the block is in the first message part then it will be metadata about the whole message:
|
447 | * meaning, description, id. Otherwise it will be metadata about the immediately preceding
|
448 | * substitution: placeholder name.
|
449 | *
|
450 | * Since blocks are optional, it is possible that the content of a message block actually starts
|
451 | * with a block marker. In this case the marker must be escaped `\:`.
|
452 | *
|
453 | * @param cooked The cooked version of the message part to parse.
|
454 | * @param raw The raw version of the message part to parse.
|
455 | * @returns An object containing the `text` of the message part and the text of the `block`, if it
|
456 | * exists.
|
457 | * @throws an error if the `block` is unterminated
|
458 | */
|
459 | export declare function ɵsplitBlock(cooked: string, raw: string): {
|
460 | text: string;
|
461 | block?: string;
|
462 | };
|
463 |
|
464 | /**
|
465 | * Translate the text of the `$localize` tagged-string (i.e. `messageParts` and
|
466 | * `substitutions`) using the given `translations`.
|
467 | *
|
468 | * The tagged-string is parsed to extract its `messageId` which is used to find an appropriate
|
469 | * `ParsedTranslation`. If this doesn't match and there are legacy ids then try matching a
|
470 | * translation using those.
|
471 | *
|
472 | * If one is found then it is used to translate the message into a new set of `messageParts` and
|
473 | * `substitutions`.
|
474 | * The translation may reorder (or remove) substitutions as appropriate.
|
475 | *
|
476 | * If there is no translation with a matching message id then an error is thrown.
|
477 | * If a translation contains a placeholder that is not found in the message being translated then an
|
478 | * error is thrown.
|
479 | */
|
480 | export declare function ɵtranslate(translations: Record<string, ɵParsedTranslation>, messageParts: TemplateStringsArray, substitutions: readonly any[]): [TemplateStringsArray, readonly any[]];
|
481 |
|
482 | /** @nodoc */
|
483 | export declare interface ɵTranslateFn {
|
484 | (messageParts: TemplateStringsArray, expressions: readonly any[]): [TemplateStringsArray, readonly any[]];
|
485 | }
|
486 |
|
487 | export { }
|