feat(@angular-devkit/build-angular): support multiple translation files per locale

This change implements the capability to specify multiple translation files per locale. The specified translation files for each locale will be merged prior to localization. The Angular configuration file has been updated to allow for both a single path string or an array of path strings when specifying the translations for each locale. If the same message identifier is present in multiple translation files, a warning will currently be issued and the last file with the duplicate message identifier will take precedence.

Closes #18276

Author: clydin

packages/angular/cli/lib/config/schema.json

@@ -418,13 +418,33 @@
                       "type": "string",
                       "description": "Localization file to use for i18n"
                     },
+                    {
+                      "type": "array",
+                      "description": "Localization files to use for i18n",
+                      "items": {
+                        "type": "string",
+                        "uniqueItems": true
+                      }
+                    },
                     {
                       "type": "object",
                       "description": "Localization options to use for the locale",
                       "properties": {
                         "translation": {
-                          "type": "string",
-                          "description": "Localization file to use for i18n"
+                          "oneOf": [
+                            {
+                              "type": "string",
+                              "description": "Localization file to use for i18n"
+                            },
+                            {
+                              "type": "array",
+                              "description": "Localization files to use for i18n",
+                              "items": {
+                                "type": "string",
+                                "uniqueItems": true
+                              }
+                            }
+                          ]
                         },
                         "baseHref": {
                           "type": "string",

packages/angular_devkit/build_angular/src/dev-server/index.ts

@@ -287,14 +287,13 @@ async function setupLocalize(
   const localeDescription = i18n.locales[locale];
   const { plugins, diagnostics } = await createI18nPlugins(
     locale,
-    localeDescription && localeDescription.translation,
+    localeDescription?.translation,
     browserOptions.i18nMissingTranslation || 'ignore',
   );
 
   // Modify main entrypoint to include locale data
   if (
-    localeDescription &&
-    localeDescription.dataPath &&
+    localeDescription?.dataPath &&
     typeof webpackConfig.entry === 'object' &&
     !Array.isArray(webpackConfig.entry) &&
     webpackConfig.entry['main']
@@ -321,7 +320,7 @@ async function setupLocalize(
           cacheIdentifier: JSON.stringify({
             buildAngular: require('../../package.json').version,
             locale,
-            translationIntegrity: localeDescription && localeDescription.integrity,
+            translationIntegrity: localeDescription?.files.map((file) => file.integrity),
           }),
           plugins,
         },

packages/angular_devkit/build_angular/src/utils/i18n-options.ts

@@ -22,11 +22,9 @@ export interface I18nOptions {
   locales: Record<
     string,
     {
-      file: string;
-      format?: string;
-      translation?: unknown;
+      files: { path: string; integrity?: string; format?: string }[];
+      translation?: Record<string, unknown>;
       dataPath?: string;
-      integrity?: string;
       baseHref?: string;
     }
   >;
@@ -35,6 +33,29 @@ export interface I18nOptions {
   veCompatLocale?: string;
 }
 
+function normalizeTranslationFileOption(
+  option: json.JsonValue,
+  locale: string,
+  expectObjectInError: boolean,
+): string[] {
+  if (typeof option === 'string') {
+    return [option];
+  }
+
+  if (Array.isArray(option) && option.every((element) => typeof element === 'string')) {
+    return option as string[];
+  }
+
+  let errorMessage = `Project i18n locales translation field value for '${locale}' is malformed. `;
+  if (expectObjectInError) {
+    errorMessage += 'Expected a string, array of strings, or object.';
+  } else {
+    errorMessage += 'Expected a string or array of strings.';
+  }
+
+  throw new Error(errorMessage);
+}
+
 export function createI18nOptions(
   metadata: json.JsonObject,
   inline?: boolean | string[],
@@ -75,32 +96,24 @@ export function createI18nOptions(
   }
 
   i18n.locales[i18n.sourceLocale] = {
-    file: '',
+    files: [],
     baseHref: rawSourceLocaleBaseHref,
   };
 
   if (metadata.locales !== undefined && !json.isJsonObject(metadata.locales)) {
     throw new Error('Project i18n locales field is malformed. Expected an object.');
   } else if (metadata.locales) {
     for (const [locale, options] of Object.entries(metadata.locales)) {
-      let translationFile;
+      let translationFiles;
       let baseHref;
       if (json.isJsonObject(options)) {
-        if (typeof options.translation !== 'string') {
-          throw new Error(
-            `Project i18n locales translation field value for '${locale}' is malformed. Expected a string.`,
-          );
-        }
-        translationFile = options.translation;
+        translationFiles = normalizeTranslationFileOption(options.translation, locale, false);
+
         if (typeof options.baseHref === 'string') {
           baseHref = options.baseHref;
         }
-      } else if (typeof options !== 'string') {
-        throw new Error(
-          `Project i18n locales field value for '${locale}' is malformed. Expected a string or object.`,
-        );
       } else {
-        translationFile = options;
+        translationFiles = normalizeTranslationFileOption(options, locale, true);
       }
 
       if (locale === i18n.sourceLocale) {
@@ -110,7 +123,7 @@ export function createI18nOptions(
       }
 
       i18n.locales[locale] = {
-        file: translationFile,
+        files: translationFiles.map((file) => ({ path: file })),
         baseHref,
       };
     }
@@ -226,33 +239,55 @@ export async function configureI18nBuild<T extends BrowserBuilderSchema | Server
         desc.dataPath = localeDataPath;
       }
 
-      if (!desc.file) {
+      if (!desc.files.length) {
         continue;
       }
 
-      const result = loader(path.join(context.workspaceRoot, desc.file));
+      for (const file of desc.files) {
+        const loadResult = loader(path.join(context.workspaceRoot, file.path));
 
-      for (const diagnostics of result.diagnostics.messages) {
-        if (diagnostics.type === 'error') {
+        for (const diagnostics of loadResult.diagnostics.messages) {
+          if (diagnostics.type === 'error') {
+            throw new Error(
+              `Error parsing translation file '${file.path}': ${diagnostics.message}`,
+            );
+          } else {
+            context.logger.warn(`WARNING [${file.path}]: ${diagnostics.message}`);
+          }
+        }
+
+        if (loadResult.locale !== undefined && loadResult.locale !== locale) {
+          context.logger.warn(
+            `WARNING [${file.path}]: File target locale ('${loadResult.locale}') does not match configured locale ('${locale}')`,
+          );
+        }
+
+        usedFormats.add(loadResult.format);
+        if (usedFormats.size > 1 && tsConfig.options.enableI18nLegacyMessageIdFormat !== false) {
+          // This limitation is only for legacy message id support (defaults to true as of 9.0)
           throw new Error(
-            `Error parsing translation file '${desc.file}': ${diagnostics.message}`,
+            'Localization currently only supports using one type of translation file format for the entire application.',
           );
-        } else {
-          context.logger.warn(`WARNING [${desc.file}]: ${diagnostics.message}`);
         }
-      }
 
-      usedFormats.add(result.format);
-      if (usedFormats.size > 1 && tsConfig.options.enableI18nLegacyMessageIdFormat !== false) {
-        // This limitation is only for legacy message id support (defaults to true as of 9.0)
-        throw new Error(
-          'Localization currently only supports using one type of translation file format for the entire application.',
-        );
+        file.format = loadResult.format;
+        file.integrity = loadResult.integrity;
+
+        if (desc.translation) {
+          // Merge translations
+          for (const [id, message] of Object.entries(loadResult.translations)) {
+            if (desc.translation[id] !== undefined) {
+              context.logger.warn(
+                `WARNING [${file.path}]: Duplicate translations for message '${id}' when merging`,
+              );
+            }
+            desc.translation[id] = message;
+          }
+        } else {
+          // First or only translation file
+          desc.translation = loadResult.translations;
+        }
       }
-
-      desc.format = result.format;
-      desc.translation = result.translation;
-      desc.integrity = result.integrity;
     }
 
     // Legacy message id's require the format of the translations
@@ -265,7 +300,12 @@ export async function configureI18nBuild<T extends BrowserBuilderSchema | Server
       i18n.veCompatLocale = buildOptions.i18nLocale = [...i18n.inlineLocales][0];
 
       if (buildOptions.i18nLocale !== i18n.sourceLocale) {
-        buildOptions.i18nFile = i18n.locales[buildOptions.i18nLocale].file;
+        if (i18n.locales[buildOptions.i18nLocale].files.length > 1) {
+          throw new Error(
+            'Localization with View Engine only supports using a single translation file per locale.',
+          );
+        }
+        buildOptions.i18nFile = i18n.locales[buildOptions.i18nLocale].files[0].path;
       }
 
       // Clear inline locales to prevent any new i18n related processing
@@ -306,12 +346,12 @@ function mergeDeprecatedI18nOptions(
     i18n.inlineLocales.add(i18nLocale);
 
     if (i18nFile !== undefined) {
-      i18n.locales[i18nLocale] = { file: i18nFile, baseHref: '' };
+      i18n.locales[i18nLocale] = { files: [{ path: i18nFile }], baseHref: '' };
     } else {
       // If no file, treat the locale as the source locale
       // This mimics deprecated behavior
       i18n.sourceLocale = i18nLocale;
-      i18n.locales[i18nLocale] = { file: '', baseHref: '' };
+      i18n.locales[i18nLocale] = { files: [], baseHref: '' };
     }
 
     i18n.flatOutput = true;

packages/angular_devkit/build_angular/src/utils/load-translations.ts

@@ -11,8 +11,10 @@ import * as fs from 'fs';
 export type TranslationLoader = (
   path: string,
 ) => {
-  translation: unknown;
+  // tslint:disable-next-line: no-implicit-dependencies
+  translations: Record<string, import('@angular/localize').ɵParsedTranslation>;
   format: string;
+  locale?: string;
   // tslint:disable-next-line: no-implicit-dependencies
   diagnostics: import('@angular/localize/src/tools/src/diagnostics').Diagnostics;
   integrity: string;
@@ -23,15 +25,14 @@ export async function createTranslationLoader(): Promise<TranslationLoader> {
 
   return (path: string) => {
     const content = fs.readFileSync(path, 'utf8');
-
     const unusedParsers = new Map();
     for (const [format, parser] of Object.entries(parsers)) {
       const analysis = analyze(parser, path, content);
       if (analysis.canParse) {
-        const translationBundle = parser.parse(path, content, analysis.hint);
+        const { locale, translations } = parser.parse(path, content, analysis.hint);
         const integrity = 'sha256-' + createHash('sha256').update(content).digest('base64');
 
-        return { format, translation: translationBundle.translations, diagnostics, integrity };
+        return { format, locale, translations, diagnostics, integrity };
       } else {
         unusedParsers.set(parser, analysis);
       }
@@ -41,7 +42,10 @@ export async function createTranslationLoader(): Promise<TranslationLoader> {
     for (const [parser, analysis] of unusedParsers.entries()) {
       messages.push(analysis.diagnostics.formatDiagnostics(`*** ${parser.constructor.name} ***`));
     }
-    throw new Error(`Unsupported translation file format in ${path}. The following parsers were tried:\n` + messages.join('\n'));
+    throw new Error(
+      `Unsupported translation file format in ${path}. The following parsers were tried:\n` +
+        messages.join('\n'),
+    );
   };
 
   // TODO: `parser.canParse()` is deprecated; remove this polyfill once we are sure all parsers provide the `parser.analyze()` method.
@@ -52,7 +56,7 @@ export async function createTranslationLoader(): Promise<TranslationLoader> {
     } else {
       const hint = parser.canParse(path, content);
 
-      return {canParse: hint !== false, hint, diagnostics};
+      return { canParse: hint !== false, hint, diagnostics };
     }
   }
 }

packages/angular_devkit/build_angular/src/utils/webpack-browser-config.ts

@@ -172,7 +172,7 @@ export async function generateI18nBrowserWebpackConfigFromContext(
 
     // Update file hashes to include translation file content
     const i18nHash = Object.values(i18n.locales).reduce(
-      (data, locale) => data + (locale.integrity || ''),
+      (data, locale) => data + locale.files.map((file) => file.integrity || '').join('|'),
       '',
     );
     if (!config.plugins) {

packages/angular_devkit/core/src/experimental/workspace/workspace-schema.json

@@ -166,13 +166,33 @@
                   "type": "string",
                   "description": "Localization file to use for i18n"
                 },
+                {
+                  "type": "array",
+                  "description": "Localization files to use for i18n",
+                  "items": {
+                    "type": "string",
+                    "uniqueItems": true
+                  }
+                },
                 {
                   "type": "object",
                   "description": "Localization options to use for the locale",
                   "properties": {
                     "translation": {
-                      "type": "string",
-                      "description": "Localization file to use for i18n"
+                      "oneOf": [
+                        {
+                          "type": "string",
+                          "description": "Localization file to use for i18n"
+                        },
+                        {
+                          "type": "array",
+                          "description": "Localization files to use for i18n",
+                          "items": {
+                            "type": "string",
+                            "uniqueItems": true
+                          }
+                        }
+                      ]
                     },
                     "baseHref": {
                       "type": "string",

tests/legacy-cli/e2e/tests/i18n/ivy-localize-merging.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright Google Inc. 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 { ng } from '../../utils/process';
+import { updateJsonFile } from '../../utils/project';
+import { setupI18nConfig } from './legacy';
+
+export default async function() {
+  // Setup i18n tests and config.
+  await setupI18nConfig(true);
+
+  // Update angular.json
+  await updateJsonFile('angular.json', workspaceJson => {
+    const appProject = workspaceJson.projects['test-project'];
+    // tslint:disable-next-line: no-any
+    const i18n: Record<string, any> = appProject.i18n;
+
+    i18n.locales['fr'] = [
+      i18n.locales['fr'],
+      i18n.locales['fr'],
+    ]
+    appProject.architect['build'].options.localize = ['fr'];
+  });
+
+  const { stderr: err1 } = await ng('build');
+  if (!err1.includes('Duplicate translations for message')) {
+    throw new Error('duplicate translations warning not shown');
+  }
+
+
+}