[BACKUP] new I18n guide #2340

Foxandxss · 2016-09-14T16:33:18Z

This supersedes #2309

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

googlebot · 2016-09-14T16:33:21Z

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.

googlebot · 2016-09-14T16:33:21Z

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.

vicb · 2016-09-14T16:53:48Z

public/docs/ts/latest/guide/i18n.jade

+include ../_util-fns
+
+:marked
+  With internationalization, also known as i18n, we can display our website in multiple languages. There are two different


what about wrapping lines ?

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

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

not in gh which is annoying for the review

ocombe · 2016-09-14T19:34:45Z

@googlebot I confirm (is this enough?)

vicb · 2016-09-14T21:23:28Z

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

ocombe · 2016-09-15T11:28:55Z

public/docs/ts/latest/guide/i18n.jade

+    * 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.


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

vicb · 2016-09-23T18:57:24Z

public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts

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


better use one and other which is the standard for en

=0 remains the same?

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

vicb · 2016-09-23T18:58:28Z

public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts

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


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

Do you have an ETA on that?

started working on that. probably 2.1 ?

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

vicb

I think this is missing

translating attrs: i18n-<attr name>
translating sibling nodes
-  ...  or
- <ng-container i18n>

vicb · 2016-09-23T18:59:24Z

public/docs/ts/latest/guide/i18n.jade

+: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.


Angular only provides 1 approach for now, full reload

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

vicb · 2016-09-23T18:59:55Z

public/docs/ts/latest/guide/i18n.jade

+
+  [Angular and i18n](#angular2-i18n)
+
+    * [i18n directive](#i18n-directive)


vicb · 2016-09-23T19:00:27Z

public/docs/ts/latest/guide/i18n.jade

+: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.


pipes also work in AoT

vicb · 2016-09-23T19:02:54Z

public/docs/ts/latest/guide/i18n.jade

+    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.


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

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

nothing currently exists

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.

vicb · 2016-09-23T19:04:05Z

public/docs/ts/latest/guide/i18n.jade

+    * 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.)


same in JiT, could be overriden by the user

Removed comparison of server being relevant in the decision process.

vicb · 2016-09-23T19:06:02Z

public/docs/ts/latest/guide/i18n.jade

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


it will never

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

vicb · 2016-09-23T19:06:22Z

public/docs/ts/latest/guide/i18n.jade

+:marked
+  ### i18n select pipe
+
+  Just like the plural pipe displays different translations based on a number, the select pipe is used to display different


do not use directly, not extracted

vicb · 2016-09-23T19:07:30Z

public/docs/ts/latest/guide/i18n.jade

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


Using git is a bad idea.

Translation tools to the rescue here

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.

vicb · 2016-09-23T19:08:32Z

public/docs/ts/latest/guide/i18n.jade

+
+  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.


xmb is the source file
xtb is the translated file

vicb · 2016-09-23T19:08:48Z

public/docs/ts/latest/guide/i18n.jade

+: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.


xlf, xlif or xtb

Is xmb not supported anymore?

Nevermind, your commend above answered my question.

filipesilva · 2016-09-24T00:36:46Z

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 · 2016-09-24T00:40:47Z

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.

vicb · 2016-09-24T01:20:33Z

public/docs/ts/latest/guide/i18n.jade

@@ -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.


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

Can you elaborate on what that means?

<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.

vicb · 2016-09-24T01:21:01Z

public/docs/ts/latest/guide/i18n.jade

 .l-main-section
 :marked
-  ### i18n directive
+  ### i18n directives


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

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?

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

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 · 2016-09-26T15:59:00Z

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.

vicb · 2016-09-26T19:56:45Z

public/docs/_examples/i18n/e2e-spec.ts

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


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

vicb

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

vicb · 2016-09-26T19:57:13Z

public/docs/_examples/i18n/e2e-spec.ts

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


Is this required in TS ?

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

vicb · 2016-09-26T19:57:39Z

public/docs/_examples/i18n/ts/app/app.module.ts

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


nit: trailing coma

We don't enforce it in the examples.

vicb · 2016-09-26T19:58:08Z

public/docs/_examples/i18n/ts/app/messages.fr.1.ts

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


explain what this is ?

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.

vicb · 2016-09-26T19:59:29Z

public/docs/_examples/package.json

@@ -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"


what is the added value of the alias ?

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

vicb · 2016-09-26T20:00:27Z

public/docs/ts/latest/guide/i18n.jade

+
+: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.


and -> can

vicb · 2016-09-26T20:08:10Z

public/docs/ts/latest/guide/i18n.jade

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


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

vicb · 2016-09-26T20:08:53Z

public/docs/ts/latest/guide/i18n.jade

+
+  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.


missing ws after comma

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

missing white space after xlf,& message should be messages

vicb · 2016-09-26T20:09:40Z

public/docs/ts/latest/guide/i18n.jade

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


format = langugage-region, ie en-US

vicb · 2016-09-26T20:10:09Z

public/docs/ts/latest/guide/i18n.jade

+  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.


localization -> locale

vicb · 2016-09-26T20:11:25Z

public/docs/ts/latest/guide/i18n.jade

+
+: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.


precompiled files ->generated templates ?

wardbell · 2016-09-27T19:42:47Z

Now superseded by #2491

docs(guide): document internationalization (i18n)

68fdbce

googlebot added CLA: no labels Sep 14, 2016

Foxandxss mentioned this pull request Sep 14, 2016

[WIP] docs(guide): document internationalization (i18n) #2309

Closed

Jesus' tweaks

cb7225e

Foxandxss force-pushed the i18n-guide branch from cb1ec9e to cb7225e Compare September 14, 2016 16:34

vicb reviewed Sep 14, 2016
View reviewed changes

docs(i18n): fix _data.json

3552db7

chore: remove typescript installation instruction

b3e44c8

ocombe reviewed Sep 15, 2016

View reviewed changes

This was referenced Sep 20, 2016

Pipes ignore user culture and use only default en-US (beating a dead horse) angular/angular#11744

Closed

Pipes ignore user culture and use only default en-US angular/angular#11710

Closed

bennett000 mentioned this pull request Sep 22, 2016

Internationalization (i18n) rangle/ngCourse2#745

Closed

filipesilva added 2 commits September 23, 2016 03:13

angular 2 -> angular

17ed3ca

Merge remote-tracking branch 'upstream/master' into i18n-guide

f727149

Foxandxss added this to the AngularConnect milestone Sep 23, 2016

Foxandxss assigned filipesilva Sep 23, 2016

vicb reviewed Sep 23, 2016

View reviewed changes

vicb suggested changes Sep 23, 2016

View reviewed changes

add base jit app

dc9bd4d

wording fixes

586f47e

vicb reviewed Sep 24, 2016

View reviewed changes

filipesilva added 12 commits September 24, 2016 02:30

add translated jit example

76848c4

add e2e test

1576c08

add jit plunker support

c48eff3

remove references to reloading

a726076

remove comparison of server requirements

c3e219c

replace directive with attribute

e413ae9

explain relevant of meaning in i18n

94b6ea2

replace git and specialized translation software for versioning

ce1de16

remove dynamic language switching

89e45d7

remove pipe usage

8b8ccf2

edit prose

635b4e4

fix code shell example

3373fad

filipesilva added the action: review-ts label Sep 26, 2016

vicb reviewed Sep 26, 2016

View reviewed changes

filipesilva added 2 commits September 26, 2016 22:58

incorporate vicb's feedback

e842200

fix typo

6ff5c74

wardbell mentioned this pull request Sep 27, 2016

docs(i18n): add internationalization (i18n) guide #2491

Merged

wardbell added the duplicate label Sep 27, 2016

wardbell closed this Sep 27, 2016

wardbell reopened this Sep 27, 2016

wardbell changed the title ~~I18n guide~~ [BACKUP] new I18n guide Sep 27, 2016

wardbell closed this Oct 5, 2016


		[Angular and i18n](#angular2-i18n)

		* [i18n directive](#i18n-directive)


		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.

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


		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.

[BACKUP] new I18n guide #2340

[BACKUP] new I18n guide #2340

Uh oh!

Conversation

Foxandxss commented Sep 14, 2016 • edited by wardbell Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

googlebot commented Sep 14, 2016

Uh oh!

googlebot commented Sep 14, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ocombe commented Sep 14, 2016

Uh oh!

vicb commented Sep 14, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vicb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

filipesilva Sep 26, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Foxandxss commented Sep 14, 2016 •

edited by wardbell

Loading

filipesilva Sep 26, 2016 •

edited

Loading