docs(localize): add public api markers for CLI integration (#39006)

This commit marks the functions and classes that are used by the CLI. PR Close #39006
angular · Sep 30, 2020 · 23e2188 · 23e2188
1 parent 5903e8a
commit 23e2188
Show file tree

Hide file tree

Showing 13 changed files with 44 additions and 8 deletions.
diff --git a/packages/localize/src/tools/src/diagnostics.ts b/packages/localize/src/tools/src/diagnostics.ts
@@ -14,6 +14,8 @@ export type DiagnosticHandlingStrategy = 'error'|'warning'|'ignore';
 /**
  * This class is used to collect and then report warnings and errors that occur during the execution
  * of the tools.
+ *
+ * @publicApi used by CLI
  */
 export class Diagnostics {
   readonly messages: {type: 'warning'|'error', message: string}[] = [];

diff --git a/packages/localize/src/tools/src/extract/extraction.ts b/packages/localize/src/tools/src/extract/extraction.ts
@@ -23,6 +23,8 @@ export interface ExtractionOptions {
 /**
  * Extracts parsed messages from file contents, by parsing the contents as JavaScript
  * and looking for occurrences of `$localize` in the source code.
+ *
+ * @publicApi used by CLI
  */
 export class MessageExtractor {
   private basePath: AbsoluteFsPath;

diff --git a/packages/localize/src/tools/src/extract/translation_files/xliff1_translation_serializer.ts b/packages/localize/src/tools/src/extract/translation_files/xliff1_translation_serializer.ts
@@ -23,6 +23,7 @@ const LEGACY_XLIFF_MESSAGE_LENGTH = 40;
  * http://docs.oasis-open.org/xliff/v1.2/xliff-profile-html/xliff-profile-html-1.2.html
  *
  * @see Xliff1TranslationParser
+ * @publicApi used by CLI
  */
 export class Xliff1TranslationSerializer implements TranslationSerializer {
   constructor(

diff --git a/packages/localize/src/tools/src/extract/translation_files/xliff2_translation_serializer.ts b/packages/localize/src/tools/src/extract/translation_files/xliff2_translation_serializer.ts
@@ -22,6 +22,7 @@ const MAX_LEGACY_XLIFF_2_MESSAGE_LENGTH = 20;
  * http://docs.oasis-open.org/xliff/xliff-core/v2.0/os/xliff-core-v2.0-os.html
  *
  * @see Xliff2TranslationParser
+ * @publicApi used by CLI
  */
 export class Xliff2TranslationSerializer implements TranslationSerializer {
   private currentPlaceholderId = 0;

diff --git a/packages/localize/src/tools/src/extract/translation_files/xmb_translation_serializer.ts b/packages/localize/src/tools/src/extract/translation_files/xmb_translation_serializer.ts
@@ -18,6 +18,7 @@ import {XmlFile} from './xml_file';
  * http://cldr.unicode.org/development/development-process/design-proposals/xmb
  *
  * @see XmbTranslationParser
+ * @publicApi used by CLI
  */
 export class XmbTranslationSerializer implements TranslationSerializer {
   constructor(private basePath: AbsoluteFsPath, private useLegacyIds: boolean) {}

diff --git a/packages/localize/src/tools/src/source_file_utils.ts b/packages/localize/src/tools/src/source_file_utils.ts
@@ -36,7 +36,9 @@ export function isNamedIdentifier(
 
 /**
  * Is the given `identifier` declared globally.
+ *
  * @param identifier The identifier to check.
+ * @publicApi used by CLI
  */
 export function isGlobalIdentifier(identifier: NodePath<t.Identifier>) {
   return !identifier.scope || !identifier.scope.hasBinding(identifier.node.name);
@@ -46,6 +48,7 @@ export function isGlobalIdentifier(identifier: NodePath<t.Identifier>) {
  * Build a translated expression to replace the call to `$localize`.
  * @param messageParts The static parts of the message.
  * @param substitutions The expressions to substitute into the message.
+ * @publicApi used by CLI
  */
 export function buildLocalizeReplacement(
     messageParts: TemplateStringsArray, substitutions: readonly t.Expression[]): t.Expression {
@@ -65,6 +68,7 @@ export function buildLocalizeReplacement(
  * to a helper function like `__makeTemplateObject`.
  *
  * @param call The AST node of the call to process.
+ * @publicApi used by CLI
  */
 export function unwrapMessagePartsFromLocalizeCall(call: NodePath<t.CallExpression>):
     [TemplateStringsArray, (ɵSourceLocation | undefined)[]] {
@@ -142,9 +146,11 @@ export function unwrapMessagePartsFromLocalizeCall(call: NodePath<t.CallExpressi
   return [ɵmakeTemplateObject(cookedStrings, rawStrings), rawLocations];
 }
 
-
-export function unwrapSubstitutionsFromLocalizeCall(call: NodePath<t.CallExpression>):
-    [t.Expression[], (ɵSourceLocation | undefined)[]] {
+/**
+ * Parse the localize call expression to extract the arguments that hold the substition expressions.
+ *
+ * @publicApi used by CLI
+ */
   const expressions = call.get('arguments').splice(1);
   if (!isArrayOfExpressions(expressions)) {
     const badExpression = expressions.find(expression => !expression.isExpression())!;
@@ -157,8 +163,11 @@ export function unwrapSubstitutionsFromLocalizeCall(call: NodePath<t.CallExpress
   ];
 }
 
-export function unwrapMessagePartsFromTemplateLiteral(elements: NodePath<t.TemplateElement>[]):
-    [TemplateStringsArray, (ɵSourceLocation | undefined)[]] {
+/**
+ * Parse the tagged template literal to extract the message parts.
+ *
+ * @publicApi used by CLI
+ */
   const cooked = elements.map(q => {
     if (q.node.value.cooked === undefined) {
       throw new BabelParseError(
@@ -172,9 +181,11 @@ export function unwrapMessagePartsFromTemplateLiteral(elements: NodePath<t.Templ
   return [ɵmakeTemplateObject(cooked, raw), locations];
 }
 
-export function unwrapExpressionsFromTemplateLiteral(quasi: NodePath<t.TemplateLiteral>):
-    [t.Expression[], (ɵSourceLocation | undefined)[]] {
-  return [quasi.node.expressions, quasi.get('expressions').map(e => getLocation(e))];
+/**
+ * Parse the tagged template literal to extract the interpolation expressions.
+ *
+ * @publicApi used by CLI
+ */
 }
 
 /**
@@ -321,6 +332,7 @@ export interface TranslatePluginOptions {
  * Translate the text of the given message, using the given translations.
  *
  * Logs as warning if the translation is not available
+ * @publicApi used by CLI
  */
 export function translate(
     diagnostics: Diagnostics, translations: Record<string, ɵParsedTranslation>,

diff --git a/packages/localize/src/tools/src/translate/source_files/es2015_translate_plugin.ts b/packages/localize/src/tools/src/translate/source_files/es2015_translate_plugin.ts
@@ -13,6 +13,12 @@ import {Diagnostics} from '../../diagnostics';
 
 import {buildCodeFrameError, buildLocalizeReplacement, isBabelParseError, isLocalize, translate, TranslatePluginOptions, unwrapMessagePartsFromTemplateLiteral} from '../../source_file_utils';
 
+/**
+ * Create a Babel plugin that can be used to do compile-time translation of `$localize` tagged
+ * messages.
+ *
+ * @publicApi used by CLI
+ */
 export function makeEs2015TranslatePlugin(
     diagnostics: Diagnostics, translations: Record<string, ɵParsedTranslation>,
     {missingTranslation = 'error', localizeName = '$localize'}: TranslatePluginOptions = {}):

diff --git a/packages/localize/src/tools/src/translate/source_files/es5_translate_plugin.ts b/packages/localize/src/tools/src/translate/source_files/es5_translate_plugin.ts
@@ -13,6 +13,12 @@ import {Diagnostics} from '../../diagnostics';
 
 import {buildCodeFrameError, buildLocalizeReplacement, isBabelParseError, isLocalize, translate, TranslatePluginOptions, unwrapMessagePartsFromLocalizeCall, unwrapSubstitutionsFromLocalizeCall} from '../../source_file_utils';
 
+/**
+ * Create a Babel plugin that can be used to do compile-time translation of `$localize` tagged
+ * messages.
+ *
+ * @publicApi used by CLI
+ */
 export function makeEs5TranslatePlugin(
     diagnostics: Diagnostics, translations: Record<string, ɵParsedTranslation>,
     {missingTranslation = 'error', localizeName = '$localize'}: TranslatePluginOptions = {}):

diff --git a/packages/localize/src/tools/src/translate/source_files/locale_plugin.ts b/packages/localize/src/tools/src/translate/source_files/locale_plugin.ts
@@ -21,6 +21,7 @@ import {isLocalize, TranslatePluginOptions} from '../../source_file_utils';
  *
  * @param locale The name of the locale to inline into the code.
  * @param options Additional options including the name of the `$localize` function.
+ * @publicApi used by CLI
  */
 export function makeLocalePlugin(
     locale: string, {localizeName = '$localize'}: TranslatePluginOptions = {}): PluginObj {

diff --git a/...ols/src/translate/translation_files/translation_parsers/simple_json_translation_parser.ts b/...ols/src/translate/translation_files/translation_parsers/simple_json_translation_parser.ts
@@ -25,6 +25,7 @@ import {ParseAnalysis, ParsedTranslationBundle, TranslationParser} from './trans
  * ```
  *
  * @see SimpleJsonTranslationSerializer
+ * @publicApi used by CLI
  */
 export class SimpleJsonTranslationParser implements TranslationParser<Object> {
   /**

diff --git a/...rc/tools/src/translate/translation_files/translation_parsers/xliff1_translation_parser.ts b/...rc/tools/src/translate/translation_files/translation_parsers/xliff1_translation_parser.ts
@@ -21,6 +21,7 @@ import {addErrorsToBundle, addParseDiagnostic, addParseError, canParseXml, getAt
  * http://docs.oasis-open.org/xliff/v1.2/xliff-profile-html/xliff-profile-html-1.2.html
  *
  * @see Xliff1TranslationSerializer
+ * @publicApi used by CLI
  */
 export class Xliff1TranslationParser implements TranslationParser<XmlTranslationParserHint> {
   /**

diff --git a/...rc/tools/src/translate/translation_files/translation_parsers/xliff2_translation_parser.ts b/...rc/tools/src/translate/translation_files/translation_parsers/xliff2_translation_parser.ts
@@ -20,6 +20,7 @@ import {addErrorsToBundle, addParseDiagnostic, addParseError, canParseXml, getAt
  * http://docs.oasis-open.org/xliff/xliff-core/v2.0/os/xliff-core-v2.0-os.html
  *
  * @see Xliff2TranslationSerializer
+ * @publicApi used by CLI
  */
 export class Xliff2TranslationParser implements TranslationParser<XmlTranslationParserHint> {
   /**

diff --git a/...e/src/tools/src/translate/translation_files/translation_parsers/xtb_translation_parser.ts b/...e/src/tools/src/translate/translation_files/translation_parsers/xtb_translation_parser.ts
@@ -22,6 +22,7 @@ import {addErrorsToBundle, addParseDiagnostic, addParseError, canParseXml, getAt
  * http://cldr.unicode.org/development/development-process/design-proposals/xmb
  *
  * @see XmbTranslationSerializer
+ * @publicApi used by CLI
  */
 export class XtbTranslationParser implements TranslationParser<XmlTranslationParserHint> {
   /**