Skip to content
This repository has been archived by the owner. It is now read-only.

[BACKUP] new I18n guide #2340

Closed
wants to merge 22 commits into from
Closed

[BACKUP] new I18n guide #2340

wants to merge 22 commits into from

Conversation

@Foxandxss
Copy link
Member

@Foxandxss Foxandxss commented Sep 14, 2016

This supersedes #2309

Now superseded by #2491. Close it when that PR is merged.

@googlebot
Copy link

@googlebot googlebot commented Sep 14, 2016

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
@googlebot
Copy link

@googlebot googlebot commented Sep 14, 2016

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.

@Foxandxss Foxandxss force-pushed the IdeaBlade:i18n-guide branch from cb1ec9e to cb7225e Sep 14, 2016
include ../_util-fns

:marked
With internationalization, also known as i18n, we can display our website in multiple languages. There are two different

This comment has been minimized.

@vicb

vicb Sep 14, 2016
Contributor

what about wrapping lines ?

don't you have a max line length on this repo.

This comment has been minimized.

@Foxandxss

Foxandxss Sep 14, 2016
Author Member

There is nothing written in stone. At the end the lines gets wrapped in the HTML

This comment has been minimized.

@vicb

vicb Sep 14, 2016
Contributor

not in gh which is annoying for the review

@ocombe
Copy link

@ocombe ocombe commented Sep 14, 2016

@googlebot I confirm (is this enough?)

@vicb
Copy link
Contributor

@vicb vicb commented Sep 14, 2016

@ocombe no, it will stay red forever when the PR author is not the same as the commit author

* No information/state is (typically) lost. The user is presumably changing the language because he could not understand the earlier language.
This means that he doesn't have unsaved information in the application.
* Tools support: the strings to translate are easily extracted from our templates.
The resulting translations are in a generic format that can be consumed both by Angular 2 and one of the many translation softwares available.

This comment has been minimized.

@ocombe

ocombe Sep 15, 2016

we should replace all "Angular 2" references with "Angular"

This comment has been minimized.

export class AppComponent {
messages: string[];
messageMapping: {[k:string]: string} = {
'=0': 'No messages.',

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

better use one and other which is the standard for en

This comment has been minimized.

@filipesilva

filipesilva Sep 24, 2016
Member

=0 remains the same?

This comment has been minimized.

@vicb

vicb Sep 24, 2016
Contributor

one and other are caterogies, =x is for discrete values, works with any x

This comment has been minimized.

// #enddocregion bootstrap-i18n

// #docregion messages-ts
export const TRANSLATION = `<?xml version="1.0" encoding="UTF-8"?>

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

FYI this will be in CompilerConfig soon, I'll try to remember to cc the doc team on the PR

This comment has been minimized.

@filipesilva

filipesilva Sep 24, 2016
Member

Do you have an ETA on that?

This comment has been minimized.

@vicb

vicb Sep 24, 2016
Contributor

started working on that. probably 2.1 ?

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

Alright, I'll leave it as is for now then we'll update it.

Copy link
Contributor

@vicb vicb left a comment

I think this is missing

  • translating attrs: i18n-<attr name>
  • translating sibling nodes
    • <!--i18n:m|d --> ... <!--/i18n --> or
    • <ng-container i18n>
:marked
With internationalization, also known as i18n, we can display our website in multiple languages. There are two different
approaches to internationalization: with AoT compilation which requires a build step and a full reload when the language changes,
or with JiT which doesn't require a full reload and uses bindings to determine when a translation is needed.

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

Angular only provides 1 approach for now, full reload

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

Removed all mentions of reloading since it's not really relevant.


[Angular and i18n](#angular2-i18n)

* [i18n directive](#i18n-directive)

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

directiveS

This comment has been minimized.

:marked
### Just in time (JiT) approach

The JiT approach relies on providing the translations to our application and binding them to our templates using directives, pipes and interpolations.

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

pipes also work in AoT

translations in the application code at build time.
* Our application must track all the pieces of the UI that need to be updated when the locale changes.
In addition, if the new language strings are being loaded over the network, this could take time and the UI needs to indicate this in some way to the user.
* Allows one to support multiple languages in the same view.

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

I think there is a confusion:
dynamic/static vs JiT/AoT

Angular always use the static approach for both AoT and JiT

Usage of pipes should be discouraged. They should only be used by the compiler to transform codes.

If you use the pipes you basically can not i18n your app because different langs use different plural category

This comment has been minimized.

@filipesilva

filipesilva Sep 24, 2016
Member

What should be used instead of the i18nSelect and i18nPlural pipes to allow for full translations?

This comment has been minimized.

@vicb

vicb Sep 24, 2016
Contributor

nothing currently exists

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

Removed mentions of dynamic language change.
Also removed the whole pipe sections, if it actively breaks language switching then we shouldn't really be describing it's use in this chapter.

* We have to reload the app to change the language.
* Extra server side support is needed: Since we generate different precompiled files for each language, the server must perform cookie/user agent analysis
to decide which localized version of the application code should be returned to the user. This also causes a cache miss.
* The server is now responsible for determining the default localized version to serve. (e.g. cookies / geo-ip / Accept-Language header, etc.)

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

same in JiT, could be overriden by the user

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

Removed comparison of server being relevant in the decision process.


.alert.is-important
:marked
The ng-xi18n messages extractor doesn't support the plural pipe right now.

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

it will never

This comment has been minimized.

@filipesilva

filipesilva Sep 24, 2016
Member

Fixed, but might required further edits to the flow of the chapter.

:marked
### i18n select pipe

Just like the plural pipe displays different translations based on a number, the select pipe is used to display different

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

do not use directly, not extracted


.alert.is-helpful
:marked
Using a versioning system such as `GIT` can help us find out easily what new translations have been generated by

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

git

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

Using git is a bad idea.

Translation tools to the rescue here

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

Removed advice to use git, replaced with specialized translation software. If you have an example of what could be used, I can add it in.


Now that we have a localized file, we can tell Angular to use it for all of our elements that have the `i18n` directive attribute.

Angular understands `xlf` and `xmb` formats, but we have to provide these message into our application.

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

xmb is the source file
xtb is the translated file

This comment has been minimized.

:marked
We have to provide three values: `TRANSLATIONS`, `TRANSLATIONS_FORMAT` and `LOCALE_ID`:
* `TRANSLATIONS` is a string containing the content of our `messages` file for the chosen localization.
* `TRANSLATIONS_FORMAT` is either `xlf` or `xmb` depending on the format of our `messages` file.

This comment has been minimized.

@vicb

vicb Sep 23, 2016
Contributor

xlf, xlif or xtb

This comment has been minimized.

@filipesilva

filipesilva Sep 24, 2016
Member

Is xmb not supported anymore?

This comment has been minimized.

@filipesilva

filipesilva Sep 24, 2016
Member

Nevermind, your commend above answered my question.

This comment has been minimized.

@filipesilva
Copy link
Member

@filipesilva filipesilva commented Sep 24, 2016

Heya @vicb, I'm picking up this chapter for now to get it ready for our testing setup and some more edits. I'm not too familiar with the i18n functionality aside from the chapter itself, so that's my starting point.

@vicb
Copy link
Contributor

@vicb vicb commented Sep 24, 2016

No pb, added a bunch of comments ping me if you need more info.

We should make it clear that i18n is supported equally well for JiT and AoT.

@@ -129,7 +129,7 @@ a(id="i18n-plural-pipe")

.alert.is-important
:marked
The ng-xi18n messages extractor doesn't support the plural pipe right now.
The ng-xi18n messages extractor doesn't support the plural pipe.

This comment has been minimized.

@vicb

vicb Sep 24, 2016
Contributor

If we want to say that we probably want to say that support for ICU messages in attributes will come soon.

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

Can you elaborate on what that means?

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

<div title="{count, plural, ...}"> will be transformed to <div title="count|i18nPlural(...)"> before compilation.

extraction:

  • {count, plural, ...} will be extracted by ng-xi18n,

merge:

  • ngc will merge the translated ICU message,
  • then ICU messages will be converted to pipes,
  • then the template is compiled.
.l-main-section
:marked
### i18n directive
### i18n directives

This comment has been minimized.

@vicb

vicb Sep 24, 2016
Contributor

It's actually not directives (notice that later in the review) - may be "markers" ?

This comment has been minimized.

@filipesilva

filipesilva Sep 24, 2016
Member

From a user perspective, under the context of the Angular docs, these look like directives. We should explain then that these are not directives if they truly aren't.

What is the difference between these and directives? Are they just meaningless attributes that are being used as a marker for ng-xi18n to pick up?

This comment has been minimized.

@filipesilva

filipesilva Sep 24, 2016
Member

Also, does this i18n attribute have any meaning outside of Angular? e.g. is it a convention, or part of a spec.

This comment has been minimized.

@vicb

vicb Sep 24, 2016
Contributor

they are just passive markers that are removed once the translations are merged

<div i18n>Hello</div> -> <div>Bonjour</div>

the name is only an ng convention

filipesilva added 12 commits Sep 24, 2016
@filipesilva
Copy link
Member

@filipesilva filipesilva commented Sep 26, 2016

The guide is heavily revised, I know that @wardbell wants to review but I would also appreciate @vicb, @ocombe and @Foxandxss to have a look. We aim to merge soon though.

We plan to further enhance it post AC, but for now the main priority is to get something simple and practical that users can follow.

Notably, I removed the pipe sections as per @vicb comment:

Usage of pipes should be discouraged. They should only be used by the compiler to transform codes.
If you use the pipes you basically can not i18n your app because different langs use different plural category

I also removed sections that talked about dynamic language switching. Angular itself doesn't support it and we don't have a server setup example to show. Also, as per @vicb:

Angular always use the static approach for both AoT and JiT

However, as @ocombe noted, this is a very common request and we should incorporate it in the guide in some form when revising.

@vicb I did not make the ICU messages note you mentioned simply because I don't know what it is nor what to say about it.

@@ -0,0 +1,13 @@
/// <reference path='../_protractor/e2e.d.ts' />
'use strict';
describe('i18n E2E Tests', function () {

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

nit: function () {...} => () => {...}

This comment has been minimized.

Copy link
Contributor

@vicb vicb left a comment

Added some "brief" comments, ping me if you need more info

@@ -0,0 +1,13 @@
/// <reference path='../_protractor/e2e.d.ts' />
'use strict';

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

Is this required in TS ?

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

In our case yes, because we there's a couple of es2015 things that node requires 'use strict'; to support.

@NgModule({
imports: [ BrowserModule ],
declarations: [ AppComponent ],
bootstrap: [ AppComponent ]

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

nit: trailing coma

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

We don't enforce it in the examples.

@@ -0,0 +1,5 @@
// #docregion
export const TRANSLATION = `

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

explain what this is ?

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

A file we need for example purpose, since our docs examples come from real files. Later in the guide we insert the content of the the .xlf file.

@@ -20,7 +20,8 @@
"test:webpack": "karma start karma.webpack.conf.js",
"build:webpack": "rimraf dist && webpack --config config/webpack.prod.js --bail",
"build:cli": "ng build",
"build:aot": "ngc -p tsconfig-aot.json && rollup -c rollup.js"
"build:aot": "ngc -p tsconfig-aot.json && rollup -c rollup.js",
"extract": "ng-xi18n"

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

what is the added value of the alias ?

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

Not having to do ./node_modules/.bin/ng-xi18n.


:marked
With internationalization, also known as i18n, we can display our website in multiple languages.
Angular provides tools to export translation files that translators and work on.

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

meaning

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

and -> can

```

This XML element represents the translation of our header tag.
You might have a different string in `id="af2ccf4b5dba59616e92cf1531505af02da8f6d2"`, this is normal.

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

The id depends on the content of the message and it's meaning

This comment has been minimized.


Now that we have a localized file, we can tell Angular to use it for all of our elements that have the `i18n` marker.

Angular understands `xlf`,`xlif` and `xtb` formats, but we have to provide these message into our application.

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

missing ws after comma

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

messages

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

I'm sorry, not sure what you mean. Can you say it another way?

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

missing white space after xlf,& message should be messages

This comment has been minimized.

In both approaches the general idea is the same. we have to give angular these three things:
* Translations file
* Translation format
* Locale ID

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

format = langugage-region, ie en-US

This comment has been minimized.

When we use JiT, we'll provide those three things when bootstrapping out `AppModule`.

We have to provide three values: `TRANSLATIONS`, `TRANSLATIONS_FORMAT` and `LOCALE_ID`.
* `TRANSLATIONS` is a string containing the content of our `messages` file for the chosen localization.

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

localization -> locale

This comment has been minimized.


:marked
That's all that we have to do! The `ngc` compiler will replace the content of our elements that have
the i18n attribute with our translations in the AoT precompiled files.

This comment has been minimized.

@vicb

vicb Sep 26, 2016
Contributor

precompiled files ->generated templates ?

This comment has been minimized.

@filipesilva

filipesilva Sep 26, 2016
Member

Replaced

filipesilva added 2 commits Sep 26, 2016
@wardbell
Copy link
Contributor

@wardbell wardbell commented Sep 27, 2016

Now superseded by #2491

@wardbell wardbell closed this Sep 27, 2016
@wardbell wardbell reopened this Sep 27, 2016
@wardbell wardbell changed the title I18n guide [BACKUP] new I18n guide Sep 27, 2016
@wardbell wardbell closed this Oct 5, 2016
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

6 participants
You can’t perform that action at this time.