From 3bbabb5dadf52ffcf05de0871176b99e0221bd77 Mon Sep 17 00:00:00 2001
From: Andy Stark <30621568+therealandeeee@users.noreply.github.com>
Date: Fri, 25 May 2018 11:10:21 +0100
Subject: [PATCH] [ADF-3087] Clarified section about adding/replacing keys in
 i18n guide (#3392)

* [ADF-3087] Clarified section about adding/replacing keys

* [ADF-3087] Corrected information in i18n and translation service docs
---
 docs/core/translation.service.md        | 22 +++++++++++++----
 docs/user-guide/internationalization.md | 33 ++++++++++++++++++++-----
 2 files changed, 44 insertions(+), 11 deletions(-)

diff --git a/docs/core/translation.service.md b/docs/core/translation.service.md
index 39ebd383e8..2147fa1586 100644
--- a/docs/core/translation.service.md
+++ b/docs/core/translation.service.md
@@ -70,7 +70,7 @@ general format of the path to this folder will be:
 
 `<app>/src/assets/my-translations/i18n`
 
-If you wanted English and French translations then you would copy the built-in
+If you wanted English and French translations then you would add
 `en.json` and `fr.json` files into the `i18n` folder and add your new keys:
 
     // en.json
@@ -84,6 +84,22 @@ If you wanted English and French translations then you would copy the built-in
       "WELCOME_MESSAGE": "Bienvenue !"
         ...
 
+The files follow the same hierarchical key:value JSON format as the built-in translations.
+You can add new keys to your local files or redefine existing keys but the built-in definitions
+will be used for any keys you don't explicitly define in your files. For example, `en.json` might
+look like the following:
+
+```json
+{
+  "title": "my app",
+  "LOGIN": {
+     "LABEL": {
+        "LOGIN": "Custom Sign In"
+     }
+  }
+}
+```
+
 To enable the new translations in your app, you also need to register them in your
 `app.module.ts` file. Import `TRANSLATION_PROVIDER` and add the path of your
 translations folder to the `providers`:
@@ -128,10 +144,6 @@ ngOnInit() {
   ...
 ```
 
-The new translation files completely replace the built-in ones.
-If you want to continue using the built-in keys then you must add your new
-keys to copies of the existing files.
-
 Note: the `source` property points to the web application root. Ensure you have
 webpack correctly set up to copy all the i18n files at compile time.
 
diff --git a/docs/user-guide/internationalization.md b/docs/user-guide/internationalization.md
index 5517ad19e7..cab65865ff 100644
--- a/docs/user-guide/internationalization.md
+++ b/docs/user-guide/internationalization.md
@@ -14,7 +14,7 @@ fairly straightforward to maintain.
 -   [I18n concepts](#i18n-concepts)
 -   [ADF support for i18n](#adf-support-for-i18n)
 -   [Using the translate pipe](#using-the-translate-pipe)
--   [Adding your own messages](#adding-your-own-messages)
+-   [Adding and replacing messages](#adding-and-replacing-messages)
 -   [Interpolations](#interpolations)
 -   [Selecting the display language](#selecting-the-display-language)
 -   [Support for i18n within ADF components](#support-for-i18n-within-adf-components)
@@ -149,13 +149,34 @@ component's `.ts` file:
 
 <!-- {% endraw %} -->
 
-## Adding your own messages
+## Adding and replacing messages
 
 The built-in translations certainly won't cover everything you will need for
-your app but you can easily replace them with your own lists. This involves
-making copies of the existing lists in your app's folder and adding your
-own keys. See the [Translation service](../core/translation.service.md) page for
-full details and examples.
+your app but you can easily replace them with your own lists. This enables you
+to add new keys and also replace the text of existing keys with your own.
+
+To modify the default translations, you need to create local translation source files
+(en.json, fr.json, etc) within your application. The local files have the same basic
+hierarchical key:value structure as the built-in translations. You can add new keys to
+your local files to extend the default set or override a default translation by redefining
+an existing key with new message text. The default translations will be used for any keys
+that you don't explicitly override. For example, your local `en.json` might look like the
+following:
+
+```json
+{
+  "title": "my app",
+  "LOGIN": {
+     "LABEL": {
+        "LOGIN": "Custom Sign In"
+     }
+  }
+}
+```
+
+The [Translation service](../core/translation.service.md) page has full details
+of how to add custom translations, including the locations of the required files
+and code samples for enabling the new translations in your app.
 
 ## Interpolations