[i18n] $localize extract translation unit & documentation

[luchillo17]

🚀 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]

This is being worked on #32912

[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 🤫

[luchillo17]

🤐

[spock123]

@petebacondarwin But it works so great... we've been able to ditch all runtime translations now, thanks to $localize .. it's wonderful

[xiaoxiangmoe]

@petebacondarwin can we use $localize in ng-packagr in Angular 10?

[petebacondarwin]

Once #32912 lands and we get it integrated into the CLI then I think we should be fine to use $localize.

I don't believe that ng-packagr will do anything with $localize. It should just pass them through so that the application can do the translation. This leaves us with a new interesting question of how to best support a library author providing translations for their library. I.E. can we merge translation files when translating; and/or filter out translations from libraries when extracting.

[xiaoxiangmoe]

@petebacondarwin Should I open an issue about how to best support a library author providing translations for their library

[petebacondarwin]

Yes! Please do. This is something that we need to improve.

[petebacondarwin]

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