docs(i18n): add internationalization (i18n) guide #2491
Conversation
|
We found a Contributor License Agreement for you (the sender of this pull request) and all commit authors, but as best as we can tell these commits were authored by someone else. If that's the case, please add them to this pull request and have them confirm that they're okay with these commits being contributed to Google. If we're mistaken and you did author these commits, just reply here to confirm. |
1 similar comment
|
We found a Contributor License Agreement for you (the sender of this pull request) and all commit authors, but as best as we can tell these commits were authored by someone else. If that's the case, please add them to this pull request and have them confirm that they're okay with these commits being contributed to Google. If we're mistaken and you did author these commits, just reply here to confirm. |
|
Very happy that documentation will be added :)
It could be that it's being worked on, but for clarity it's good to highlight that. |
|
@rolandoldengarm This is a minimum, introductory chapter. We'll be revising as more i18n features and ergonomics arrive. Thanks for the feedback though. |
wardbell
force-pushed
the
docs-i18n-guide
branch
4 times, most recently
from
a5b8267 to
ed95dab
Compare
wardbell
force-pushed
the
docs-i18n-guide
branch
2 times, most recently
from
27032d3 to
0b6443f
Compare
|
@rolandoldengarm Almost ready with this PR. Quick answers to your questions:
This makes sense to me. The facility described here is for static content in the component templates, not live content from a database. Therefore, there is no obvious benefit to re-translating fixed text for every component as it loads. That would make the page slower and heavier. It seems also a safe bet that users aren't changing language in the middle of their work. A page re-load at the start (if you loaded the wrong version), is a small price for smooth running throughout the session.
Cheers. |
wardbell
force-pushed
the
docs-i18n-guide
branch
from
0b6443f to
3ee3778
Compare
| const noProviders: Object[] = []; | ||
|
|
||
| // No locale or English: no translation providers | ||
| if (!locale || locale === 'en') { |
| include ../_util-fns | ||
|
|
||
| :marked | ||
| Angular's _internationalization_ ("_i18n_") tools help make your app availble in multiple languages. |
|
|
||
| .alert.is-helpful | ||
| :marked | ||
| `i18n` is not an Angular _directive_. It's a custom _attribute_, recognized by Angular tools and compilers. |
There was a problem hiding this comment.
it gets remove at compile time
(this is actually only true when a i18n file is provided to ngc for now but eventually it will always)
| While all appearance of a message with the _same_ meaning should have the _same_ translation, | ||
| a message with *different meanings* could have different translations. | ||
| The Angular extraction tool preserves both the _meaning_ and the _description_ in the translation source file | ||
| to facilitiate contextually-specific transations. |
|
|
||
| Use the `ng-xi18n` extraction tool to generate a translation source file in an industry standard format. | ||
|
|
||
| This is an Angular CLI tool based on the `ngc` compiler in the `@angular/compiler-cli` npm package. |
There was a problem hiding this comment.
again I don't see the need to mention ngc here
| a#translate | ||
| .l-main-section | ||
| :marked | ||
| ## Translate _le message textuel_ |
There was a problem hiding this comment.
"le message textuel" reminds me of my english :)
| You will probably translate into more than one other language so it's a good idea | ||
| for the project structure to reflect your entire internationalization effort. | ||
|
|
||
| One approach is to create an `i18n` folder with subfolders for each language or locale, e.g. `i18n/fr` for French. |
There was a problem hiding this comment.
I think 'locale/messages.fr.xlf` is more "standard"
| +makeExample('cb-i18n/ts/i18n/fr/messages.fr.xlf.html', 'trans-unit', 'i18n/fr/messages.fr.xlf (<trans-unit>, after translation)')(format=".") | ||
| :marked | ||
| Note that the `id` is generated by the tool. Don't touch it. | ||
| Its value depends on the content of the message, its meaning, and its description. |
There was a problem hiding this comment.
not the description, only text + meaning
|
@wardbell Thank you very much, appreciate your reply! Reloading app is no problem, and for my other issue there seems to be a solution as well. |
not yet. you can up vote angular/angular#11405 |
Ward's edited review of the @ocombe, @Foxandxss, @filipesilva original based on PR #2340.
Re-branched in case someone needs to go back to the unsquashed #2340