From d9cde61fd919bf8ce19216579f1358e9ca94e6e2 Mon Sep 17 00:00:00 2001 From: David Shevitz Date: Tue, 27 Apr 2021 05:38:23 +0000 Subject: [PATCH] docs: add new migration guide to v12 documentation that describes how to migrate older localization ids to new ones --- .pullapprove.yml | 1 + .../guide/migration-legacy-message-id.md | 86 +++++++++++++++++++ aio/content/navigation.json | 5 ++ 3 files changed, 92 insertions(+) create mode 100644 aio/content/guide/migration-legacy-message-id.md diff --git a/.pullapprove.yml b/.pullapprove.yml index 58036d43c5001..5fa7951e73a8d 100644 --- a/.pullapprove.yml +++ b/.pullapprove.yml @@ -998,6 +998,7 @@ groups: 'aio/content/guide/releases.md', 'aio/content/guide/updating.md', 'aio/content/guide/deprecations.md', + 'aio/content/guide/migration-legacy-message-id.md', 'aio/content/guide/migration-renderer.md', 'aio/content/guide/migration-undecorated-classes.md', 'aio/content/guide/migration-dynamic-flag.md', diff --git a/aio/content/guide/migration-legacy-message-id.md b/aio/content/guide/migration-legacy-message-id.md new file mode 100644 index 0000000000000..f14e724e0ac54 --- /dev/null +++ b/aio/content/guide/migration-legacy-message-id.md @@ -0,0 +1,86 @@ +# Migrating legacy localization IDs + +## Why this migration is necessary + +The Angular translation system works by matching a message ID to a translated message in a different language. One option for creating these IDs is to have the translation system generate them for you. Previously, the format for these IDs are not stable when there are insignificant changes, such as to whitespace. The new format is much more robust. + +This topic describes how to migrate old localization IDs to help you future-proof your application in the event that the old format is removed. + +## What this migration does + +Angular version 11 introduced a new format for generating localization IDs. These new IDs are more robust than the previous legacy format. However, applications created before version 11 still used the legacy format for their IDs. + +
+ +You do not need to migrate custom localization IDs to new IDs. + +
+ +With the release of Angular version 12, you now have how tools available to help you migrate any legacy localization IDs to IDs that use the latest algorithms. + +You have two options for migrating legacy IDs. The first method uses the Angular CLI to locate legacy IDs in your application. The second method uses a standalone script, `localize-extract`, to locate the legacy IDs. + +## Migrating legacy IDs using the CLI + +To migrate legacy localization IDs using the CLI: + +1. Run the `ng extract-i18n` command. + + + ng extract-i18n --format=legacy-migrate + + + After running this command, you have a migration file, `messages.json`, containing a mapping between legacy localization IDs and new IDs that you can use to update your application. + +1. Update the IDs in your application using the `npx localize-migrate` command. + + + npx localize-migrate --files=*.xlf --mapFile=messages.json + + +
+ + You can also specify other formats in the `files` parameter, such as `*.xmb`. + +
+ +1. Commit the updated files to your source control system. + +After you complete the migration, set the Angular Compiler option, `enableI18nLegacyMessageIdFormat`, to `false`. For more information about this option, see [Angular Compiler Options](/guide/angular-compiler-options#enablei18nlegacymessageidformat). + +## Migrate legacy IDs using `localize-extract` + +If you are not using the Angular CLI, you can migrate legacy localization IDs using `localize-extract`: + +1. Run the `npx localize-extract` command. + + + npx localize-extract --format=legacy-migrate --source=./path/to/bundles/**/*.js --outputPath=./messages.json + + + In this command, `./path/to/bundles/` represents the path to your distributable files. You can set the `outputPath` parameter to any directory in your system. + +
+ + Your distributable files must not have been translated, such as by using `localize-translate`, as doing so strips the `$localize` tagged strings that the extractor requires. + +
+ + After running this command, you have a migration file, `messages.json`, containing a mapping between legacy localization IDs and new IDs that you can use to update your application. + +1. Update the IDs in your application using the `npx localize-migrate` command. + + + npx localize-migrate --files=*.xlf --mapFile=messages.json + + +
+ + You can also specify other formats in the `files` parameter, such as `*.xmb`. + +
+ +After you complete the migration, set the Angular Compiler option, `enableI18nLegacyMessageIdFormat`, to `false`. For more information about this option, see [Angular Compiler Options](/guide/angular-compiler-options#enablei18nlegacymessageidformat). + +{@searchKeywords i18n} + diff --git a/aio/content/navigation.json b/aio/content/navigation.json index cff46211fbfcb..38bb3a6bf3f18 100644 --- a/aio/content/navigation.json +++ b/aio/content/navigation.json @@ -658,6 +658,11 @@ "url": "guide/ivy-compatibility", "title": "Ivy Compatibility Guide", "tooltip": "Details to help you make sure your application is compatible with Ivy." + }, + { + "url": "guide/migration-legacy-message-id", + "title": "Migration: Legacy Localization IDs", + "tooltip": "Learn how to migrate legacy IDs for localization to new, more stable ones." } ] },