将翻译结果合并到应用程序中

要将完成的翻译结果合并到你的项目中，请完成以下操作

1. 使用 Angular CLI 构建项目的可分发文件的副本
2. 使用 ​"localize"​ 选项将所有 i18n 消息替换为有效的翻译并构建本地化的应用程序变体。应用程序变体就是为单个语言环境翻译的应用程序的可分发文件的完整副本。

合并翻译后，可使用服务器端语言检测或不同的子目录来提供（serve）应用程序的每个可分发副本。

对于应用程序的编译期转换，构建过程会使用预先 (AOT) 编译来生成小型、快速、可立即运行的应用程序。

要为每个语言环境构建应用程序的单独可分发副本，请在项目的 ​angular.json​ 工作区构建配置文件中在构建配置中定义语言环境。

此方法不需要为每个语言环境执行完整的应用程序构建，从而缩短了构建过程。

要为每个语言环境生成应用程序变体，请使用 ​angular.json​ 工作区构建配置文件中的 ​"localize"​ 选项。此外，要从命令行构建，请使用带有 ​--localize​ 选项的 ​build ​Angular CLI 命令。

或者，仅对一种语言环境应用特定构建选项 以自定义语言环境配置。

在构建配置中定义语言环境

使用项目的工作区构建配置文件 ​angular.json​ 中的 ​i18n ​项目选项来定义项目的语言环境。

以下子选项标识源语言并告诉编译器在哪里可以找到项目支持的翻译。

子选项	详情
sourceLocale	你在应用程序源代码中使用的语言环境（默认为 en-US）
locales	语言环境标识符到翻译文件的映射表

angular.json 用于 en-US 和 fr 示例

比如，工作区构建配置文件 ​angular.json​ 的以下代码片段会将源语言环境设置为 ​en-US​ 并提供法语 ( ​fr​ ) 语言环境翻译文件的路径。

"projects": {
    "angular.io-example": {
      // ...
      "i18n": {
        "sourceLocale": "en-US",
        "locales": {
          "fr": {
            "translation": "src/locale/messages.fr.xlf",
            // ...
          }
        }
      },
      "architect": {
        // ...
      }
    }
  }
}

为每个语言环境生成应用程序变体

要在构建配置中使用你的语言环境定义，请使用工作空间构建配置文件 ​angular.json​ 中的 ​"localize"​ 选项来告诉 CLI 要为此构建配置生成哪些语言环境。

• 对于先前在构建配置中定义的所有语言环境，将 ​"localize"​ 设置为 ​true​。
• 将 ​"localize"​ 设置为先前定义的语言环境标识符子集的数组，以单独构建那些语言环境版本。
• 将 ​"localize"​ 设置为 ​false ​以禁用本地化并且不生成任何特定于语言环境的版本。

注意：
本地化组件模板需要预先 (AOT) 编译。
如果你更改了此设置，请将 ​"aot"​ 设置为 ​true ​以使用 AOT。

由于 i18n 的部署复杂性和最小化重建时间的需要，开发服务器一次仅支持本地化单个语言环境。如果你将 ​"localize"​ 选项设置为 ​true​，定义了多个语言环境，并使用 ​ng serve​，就会发生错误。如果要针对特定语言环境进行开发，请将 ​"localize"​ 选项设置为特定的语言环境。比如，对于法语 ( ​fr ​)，请指定 ​"localize": ["fr"]​。

CLI 加载并注册语言环境数据，将每个生成的版本放置在特定语言环境的目录中以使其与其他语言环境版本分开，并将其目录放在为此项目配置的 ​outputPath ​中。对于每个应用程序变体，将 ​html ​元素的 ​lang ​属性设置为其语言环境。CLI 还通过将语言环境添加到所配置的 ​baseHref ​中来调整每个应用程序版本的 HTML baseHref。

将 ​"localize"​ 属性设置为共享配置以有效继承所有配置。此外，会将该属性设置为覆盖其他配置。

angular.json 包含构建示例中的所有语言环境

以下示例展示了如何把工作区构建配置文件 ​angular.json​ 中的 ​"localize"​ 选项设置为 ​true​，以构建构建配置中定义的所有语言环境。

"build": {
  "builder": "@angular-devkit/build-angular:browser",
  "options": {
    "localize": true,
    // ...
  },

从命令行构建

此外，可以将 ​--localize​ 选项与 ​ng build​ 命令和你现有的 ​production ​配置结合使用。CLI 会构建配置中定义的所有语言环境。如果在构建配置中设置了语言环境，则相当于将 ​"localize"​ 选项设置为 ​true​。

ng build --localize

仅对一种语言环境应用特定的构建选项

要将特定构建选项仅应用于一个语言环境，请指定单个语言环境以创建自定义的语言环境专有配置。

请使用只有一个语言环境的 Angular CLI 开发服务器 ( ​ng serve​ )。

为法语构建的例子

以下示例显示使用单个语言环境的自定义语言环境专属配置。

"build": {
    // ...
    "configurations": {
      // ...
      "fr": {
        "localize": ["fr"]
      }
    },
    // ...
  },
  "serve": {
    "builder": "@angular-devkit/build-angular:dev-server",
    "configurations": {
      // ...
      "fr": {
        "browserTarget": "angular.io-example:build:development,fr"
      }
    },
    // ...
  },
  // ...
}

将此配置传递给 ​ng serve​ 或 ​ng build​ 命令。以下代码示例显示了如何提供法语文件。

ng serve --configuration=fr

对于生产构建，可使用配置组合来同时运行这两种配置。

ng build --configuration=production,fr

"architect": {
  "build": {
    "builder": "@angular-devkit/build-angular:browser",
    "options": {
      // ...
    },
    "configurations": {
      // ...
      "fr": {
        "localize": ["fr"]
      }
    },
    // ...
  },
  "serve": {
    "builder": "@angular-devkit/build-angular:dev-server",
    "configurations": {
      "production": {
        "browserTarget": "angular.io-example:build:production"
      },
      // ...
      "fr": {
        "browserTarget": "angular.io-example:build:development,fr"
      }
    },
    // ...
  },
  // ...
}

报告缺失的翻译

当缺少翻译时，可以构建成功但会生成警告，比如 ​Missing translation for message "{translation_text}"​。要配置 Angular 编译器生成的警告级别，请指定以下级别之一。

警告级别	详情	输出
error	抛出错误，构建失败	不适用
ignore	什么也不做	不适用
warning	在控制台或 shell 中显示默认警告	Missing translation for message "{translation_text}"

在工作区构建配置文件 ​angular.json​ 中 ​build ​目标的 ​options ​部分指定警告级别。

angular.json error 警告级别示例

以下示例显示如何将警告级别设置为 ​error​。

"build": {
  "builder": "@angular-devkit/build-angular:browser",
  "options": {
    // ...
    "i18nMissingTranslation": "error"
  },

当你将 Angular 项目编译为 Angular 应用程序时，​i18n​ 属性的实例将被替换为 ​$localize​ 标记的消息字符串的实例。这意味着你的 Angular 应用程序会在编译后被翻译。这也意味着你可以创建 Angular 应用程序的本地化版本，而无需为每个语言环境重新编译整个 Angular 项目。
当你翻译 Angular 应用程序时，翻译转换会用翻译集合中的字符串替换和重新排序模板文字字符串的部分（静态字符串和表达式）。