@angular/localize
Version:
Angular - library for localizing messages
80 lines (79 loc) • 3.04 kB
TypeScript
/**
* @license
* Copyright Google LLC All Rights Reserved.
*
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.dev/license
*/
import { MessageId, ɵParsedTranslation } from '../../../../../index';
import { Diagnostics } from '../../../diagnostics';
/**
* Indicates that a parser can parse a given file, with a hint that can be used to speed up actual
* parsing.
*/
export interface CanParseAnalysis<Hint> {
canParse: true;
diagnostics: Diagnostics;
hint: Hint;
}
/**
* Indicates that a parser cannot parse a given file with diagnostics as why this is.
* */
export interface CannotParseAnalysis {
canParse: false;
diagnostics: Diagnostics;
}
/**
* Information about whether a `TranslationParser` can parse a given file.
*/
export type ParseAnalysis<Hint> = CanParseAnalysis<Hint> | CannotParseAnalysis;
/**
* An object that holds translations that have been parsed from a translation file.
*/
export interface ParsedTranslationBundle {
locale: string | undefined;
translations: Record<MessageId, ɵParsedTranslation>;
diagnostics: Diagnostics;
}
/**
* Implement this interface to provide a class that can parse the contents of a translation file.
*
* The `analyze()` method can return a hint that can be used by the `parse()` method to speed
* up parsing. This allows the parser to do significant work to determine if the file can be parsed
* without duplicating the work when it comes to actually parsing the file.
*
* Example usage:
*
* ```ts
* const parser: TranslationParser = getParser();
* const analysis = parser.analyze(filePath, content);
* if (analysis.canParse) {
* return parser.parse(filePath, content, analysis.hint);
* }
* ```
*/
export interface TranslationParser<Hint = true> {
/**
* Analyze the file to see if this parser can parse the given file.
*
* @param filePath The absolute path to the translation file.
* @param contents The contents of the translation file.
* @returns Information indicating whether the file can be parsed by this parser.
*/
analyze(filePath: string, contents: string): ParseAnalysis<Hint>;
/**
* Parses the given file, extracting the target locale and translations.
*
* Note that this method should not throw an error. Check the `bundle.diagnostics` property for
* potential parsing errors and warnings.
*
* @param filePath The absolute path to the translation file.
* @param contents The contents of the translation file.
* @param hint A value that can be used by the parser to speed up parsing of the file. This will
* have been provided as the return result from calling `analyze()`.
* @returns The translation bundle parsed from the file.
* @throws No errors. If there was a problem with parsing the bundle will contain errors
* in the `diagnostics` property.
*/
parse(filePath: string, contents: string, hint: Hint): ParsedTranslationBundle;
}