refactor(@angular-devkit/build-angular): restructure i18n extraction builder to allow for application builder support

The `extract-i18n` builder code has been restructured in a similar fashion to the `dev-server` builder.
This refactor provides the groundwork to add support for the `application` and `browser-esbuild` builders
during message extraction.
The webpack related logic has been split into a separate file and is dynamically imported when needed.
Additionally the options processing has been moved to a separate file and the `index.ts` now only exports
instead of previously containing most of the builder logic.

Author: clydin

goldens/public-api/angular_devkit/build_angular/index.md

@@ -6,7 +6,6 @@
 
 import { BuilderContext } from '@angular-devkit/architect';
 import { BuilderOutput } from '@angular-devkit/architect';
-import { BuildResult } from '@angular-devkit/build-webpack';
 import type { ConfigOptions } from 'karma';
 import { Configuration } from 'webpack';
 import { DevServerBuildOutput } from '@angular-devkit/build-webpack';
@@ -153,7 +152,7 @@ export function executeDevServerBuilder(options: DevServerBuilderOptions, contex
 // @public
 export function executeExtractI18nBuilder(options: ExtractI18nBuilderOptions, context: BuilderContext, transforms?: {
     webpackConfiguration?: ExecutionTransformer<webpack.Configuration>;
-}): Promise<BuildResult>;
+}): Promise<BuilderOutput>;
 
 // @public
 export function executeKarmaBuilder(options: KarmaBuilderOptions, context: BuilderContext, transforms?: {
@@ -175,8 +174,14 @@ export function executeServerBuilder(options: ServerBuilderOptions, context: Bui
 // @public
 export type ExecutionTransformer<T> = (input: T) => T | Promise<T>;
 
-// @public (undocumented)
-export type ExtractI18nBuilderOptions = Schema;
+// @public
+export interface ExtractI18nBuilderOptions {
+    browserTarget: string;
+    format?: Format;
+    outFile?: string;
+    outputPath?: string;
+    progress?: boolean;
+}
 
 // @public (undocumented)
 export interface FileReplacement {

packages/angular_devkit/build_angular/src/builders/extract-i18n/builder.ts

@@ -0,0 +1,173 @@
+/**
+ * @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.io/license
+ */
+
+import type { Diagnostics } from '@angular/localize/tools';
+import type { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
+import fs from 'node:fs';
+import path from 'node:path';
+import type webpack from 'webpack';
+import type { ExecutionTransformer } from '../../transforms';
+import { loadEsmModule } from '../../utils/load-esm';
+import { purgeStaleBuildCache } from '../../utils/purge-cache';
+import { assertCompatibleAngularVersion } from '../../utils/version';
+import { normalizeOptions } from './options';
+import { Schema as ExtractI18nBuilderOptions, Format } from './schema';
+
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
+export async function execute(
+  options: ExtractI18nBuilderOptions,
+  context: BuilderContext,
+  transforms?: {
+    webpackConfiguration?: ExecutionTransformer<webpack.Configuration>;
+  },
+): Promise<BuilderOutput> {
+  // Determine project name from builder context target
+  const projectName = context.target?.project;
+  if (!projectName) {
+    context.logger.error(`The 'extract-i18n' builder requires a target to be specified.`);
+
+    return { success: false };
+  }
+
+  // Check Angular version.
+  assertCompatibleAngularVersion(context.workspaceRoot);
+
+  // Load the Angular localize package.
+  // The package is a peer dependency and might not be present
+  let localizeToolsModule;
+  try {
+    localizeToolsModule = await loadEsmModule<typeof import('@angular/localize/tools')>(
+      '@angular/localize/tools',
+    );
+  } catch {
+    return {
+      success: false,
+      error: `i18n extraction requires the '@angular/localize' package.`,
+    };
+  }
+
+  // Purge old build disk cache.
+  await purgeStaleBuildCache(context);
+
+  // Normalize options
+  const normalizedOptions = await normalizeOptions(context, projectName, options);
+  const builderName = await context.getBuilderNameForTarget(normalizedOptions.browserTarget);
+
+  // Extract messages based on configured builder
+  // TODO: Implement application/browser-esbuild support
+  let extractionResult;
+  if (
+    builderName === '@angular-devkit/build-angular:application' ||
+    builderName === '@angular-devkit/build-angular:browser-esbuild'
+  ) {
+    return {
+      error: 'i18n extraction is currently only supported with the "browser" builder.',
+      success: false,
+    };
+  } else {
+    const { extractMessages } = await import('./webpack-extraction');
+    extractionResult = await extractMessages(normalizedOptions, builderName, context, transforms);
+  }
+
+  // Return the builder result if it failed
+  if (!extractionResult.builderResult.success) {
+    return extractionResult.builderResult;
+  }
+
+  // Perform duplicate message checks
+  const { checkDuplicateMessages } = localizeToolsModule;
+
+  // The filesystem is used to create a relative path for each file
+  // from the basePath.  This relative path is then used in the error message.
+  const checkFileSystem = {
+    relative(from: string, to: string): string {
+      return path.relative(from, to);
+    },
+  };
+  const diagnostics = checkDuplicateMessages(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    checkFileSystem as any,
+    extractionResult.messages,
+    'warning',
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    extractionResult.basePath as any,
+  );
+  if (diagnostics.messages.length > 0) {
+    context.logger.warn(diagnostics.formatDiagnostics(''));
+  }
+
+  // Serialize all extracted messages
+  const serializer = await createSerializer(
+    localizeToolsModule,
+    normalizedOptions.format,
+    normalizedOptions.i18nOptions.sourceLocale,
+    extractionResult.basePath,
+    extractionResult.useLegacyIds,
+    diagnostics,
+  );
+  const content = serializer.serialize(extractionResult.messages);
+
+  // Ensure directory exists
+  const outputPath = path.dirname(normalizedOptions.outFile);
+  if (!fs.existsSync(outputPath)) {
+    fs.mkdirSync(outputPath, { recursive: true });
+  }
+
+  // Write translation file
+  fs.writeFileSync(normalizedOptions.outFile, content);
+
+  return extractionResult.builderResult;
+}
+
+async function createSerializer(
+  localizeToolsModule: typeof import('@angular/localize/tools'),
+  format: Format,
+  sourceLocale: string,
+  basePath: string,
+  useLegacyIds: boolean,
+  diagnostics: Diagnostics,
+) {
+  const {
+    XmbTranslationSerializer,
+    LegacyMessageIdMigrationSerializer,
+    ArbTranslationSerializer,
+    Xliff1TranslationSerializer,
+    Xliff2TranslationSerializer,
+    SimpleJsonTranslationSerializer,
+  } = localizeToolsModule;
+
+  switch (format) {
+    case Format.Xmb:
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return new XmbTranslationSerializer(basePath as any, useLegacyIds);
+    case Format.Xlf:
+    case Format.Xlif:
+    case Format.Xliff:
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return new Xliff1TranslationSerializer(sourceLocale, basePath as any, useLegacyIds, {});
+    case Format.Xlf2:
+    case Format.Xliff2:
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return new Xliff2TranslationSerializer(sourceLocale, basePath as any, useLegacyIds, {});
+    case Format.Json:
+      return new SimpleJsonTranslationSerializer(sourceLocale);
+    case Format.LegacyMigrate:
+      return new LegacyMessageIdMigrationSerializer(diagnostics);
+    case Format.Arb:
+      const fileSystem = {
+        relative(from: string, to: string): string {
+          return path.relative(from, to);
+        },
+      };
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return new ArbTranslationSerializer(sourceLocale, basePath as any, fileSystem as any);
+  }
+}