[i18n] $localize extract translation unit & documentation

🚀 feature request

Relevant Package

This feature request is for @angular/localize

Description

Currently, the $localize API is not documented, and translation text & id is not extracted towards translation file, basically the translation units for a text translated with $localize in code have to be put in a translation unit in the file manually.

If you have many items to translate with $localize it will add load to the team, it multiplies the load by the number of locales you need to support, since each time you merge the source locale into any other locale file, with the VSCode Angular i18n plugin (and very likely with many other xlf merge utilities), those translation units you added manually will be removed and you’re forced to either look into git to undo those you added by hand or add them back again.

Here’s the math, if you have, say 10 items localized from code, you support 10 languages or locales, you have to re-visit 100 translation units every time you make changes that require changes in the source locale file, which is very often when you make new features or fix a typo, adding tons of load, not to mention being highly error-prone.

Describe the solution you’d like

All $localize calls are extracted into the translation file as translation units, and documentation is updated.

Describe alternatives you’ve considered

At the very least make the extraction work, I could take care of the docs later since I’ve meddled quite a bit with the $localize API for enterprise projects:

[petebacondarwin]

#32912 is now available on 10.1.0-next.0 release.

[petebacondarwin]

And $localize as an API was not made public in v9. That is why it is not yet documented. In v9 we just used it internally for template translations. The fact that you can use it in your own TS code is supposed to be a secret 🤫