[ADF-3731] Added more detail about locale language selection (#3959)

docs/core/language-menu.component.md

@@ -1,17 +1,18 @@
 ---
 Added: v2.0.0
 Status: Active
+Last reviewed: 2018-11-09
 ---
 
 # Language Menu component
 
-Displays all the languages that are present in the "app.config.json" or the default one (EN).
+Displays all the languages that are present in "app.config.json" and the default (EN).
 
 ![Language Menu screenshot](../docassets/images/languages-menu.png)
 
 ## Basic usage
 
-How to attach an ADF Language Menu as main menu
+How to attach an ADF Language Menu as a main menu
 
 ```html
 <button mat-icon-button [matMenuTriggerFor]="langMenu">
@@ -24,9 +25,13 @@ How to attach an ADF Language Menu as main menu
 
 ## Details
 
-In the previous example we are using the ADF Language Menu as main menu.
-The [Language Menu component](../core/language-menu.component.md) is able to fetch all the languages from the "app.config.json".
-This is how the configuration looks like in the the "app.config.json"
+Add a [Language Menu component](../core/language-menu.component.md) to let the
+user set the locale language for the app. For further information about the
+locale language, see the
+[Internationalization](../user-guide/internationalization.md#how-the-display-language-is-selected)
+page in the user guide.
+
+The component fetches the list of available languages from `app.config.json`:
 
 ```json
 "languages": [
@@ -45,11 +50,11 @@ This is how the configuration looks like in the the "app.config.json"
     ]
 ```
 
-In case no setting is provided, the component shows only the English language.
+If no `languages` setting is provided, the component shows only the English language.
 
 ### Nested Menu language
 
-How to attach an ADF Language Menu as nested menu
+You can also attach the Language Menu as a nested menu:
 
 ```html
 <button mat-icon-button class="dw-profile-menu" [matMenuTriggerFor]="profileMenu">
@@ -67,10 +72,6 @@ How to attach an ADF Language Menu as nested menu
 
 ![Nested Language Menu screenshot](../docassets/images/languages-menu-nested.png)
 
-### Nested menu details
-
-In the previous example we are using the ADF Language Menu as nested menu.
-
 ## See Also
 
 -   [Internationalization](../user-guide/internationalization.md)

docs/user-guide/internationalization.md

@@ -17,7 +17,7 @@ fairly straightforward to maintain.
 -   [Using the translate pipe](#using-the-translate-pipe)
 -   [Adding and replacing messages](#adding-and-replacing-messages)
 -   [Interpolations](#interpolations)
--   [Selecting the display language](#selecting-the-display-language)
+-   [How the display language is selected](#how-the-display-language-is-selected)
 -   [Support for i18n within ADF components](#support-for-i18n-within-adf-components)
 -   [See also](#see-also)
 
@@ -227,19 +227,42 @@ You can use interpolations with the `translate` pipe in a similar way:
 
 <!-- {% endraw %} -->
 
-## Selecting the display language
+## How the display language is selected
 
-ADF provides a [Language Menu component](../core/language-menu.component.md) that
-you can add to a page to let the user choose their preferred language. The
-available languages are defined in the `app.config.json` file for the app.
+The `locale` preference in the [user preferences](../core/user-preferences.service.md)
+contains the language code that will be used to display the ADF app. Since the user
+preferences can only be saved by the app when it runs, they will not immediately be available when
+the app launches for the first time. The app uses the following priorities to determine
+the locale language for the first launch:
 
-Note that when the user selects an item from the menu, it simply changes the "locale"
-preference (which you can get via the [User Preferences service](../core/user-preferences.service.md)).
-The `translate` pipe reacts automatically to this and changes the page text
-immediately to the new language. However, text added via a variable set using
-[`TranslationService`](../core/translation.service.md)`.get`, as in the example above, will not be updated like this;
-you will need to get a new translation and set the variable's value again explicitly
-from the code.
+1. If the `locale` property is set in `app.config.json` then this will be used.
+1. If there is no `locale` property then the browser's language setting will be used instead.
+1. If neither of the first two options is available then English will be used by default.
+
+The table below illustrates how the selection is made:
+
+| User Preference | `locale` in `app.config.json` | Browser language | Default | Result |
+| -- | -- | -- | -- | -- |
+| X | X | X | en | en |
+| X | X | jp | en | jp |
+| X | fr | jp | en | fr |
+| it | fr | jp | en | it |
+
+Once the locale language is determined, it is saved to the user preferences and this saved value
+will be used from that point on, regardless of the `app.config.json` and browser settings.
+
+However, you can change the `locale` user preference from code using the
+[User Preferences service](../core/user-preferences.service.md) and the updated value
+will still override any browser or `app.config.json` settings.
+ADF also provides a [Language Menu component](../core/language-menu.component.md) that
+you can add to a page to let the user set the `locale` preference easily. The
+list of available languages is defined in the `app.config.json` file for the app.
+
+The `translate` pipe reacts automatically to a change in the locale language and
+immediately updates the display. However, text added via a variable set using
+[`TranslationService`](../core/translation.service.md)`.get`, as in the example above, will not be
+updated directly in this way. Instead, you will need to get a new translation and set the
+variable's value again explicitly from the code.
 
 See the [Language Menu component](../core/language-menu.component.md) page for further
 details and usage examples.