From 233cf767b248373e1557e203cf5b91663d0b71a3 Mon Sep 17 00:00:00 2001
From: Ryan Mathis <rmathis@unicon.net>
Date: Fri, 28 Sep 2018 11:22:46 -0700
Subject: [PATCH] SHIBUI-813 Updated documentation on how to set translations

---
 INTERNATIONALIZATION.md | 42 +++++++++++++++++++++++++++++------------
 ui/README.md            | 11 -----------
 2 files changed, 30 insertions(+), 23 deletions(-)

diff --git a/INTERNATIONALIZATION.md b/INTERNATIONALIZATION.md
index 0240826a6..c6aadf2e1 100644
--- a/INTERNATIONALIZATION.md
+++ b/INTERNATIONALIZATION.md
@@ -2,13 +2,29 @@
 
 ## About
 
-The Shibboleth UI leverages Angular's built in internationalization (i18n)
-system feature to allow for localization of the views.
+The Shibboleth UI leverages the messages_*_*.properties files common to Java/Spring applications. The default files are located in `backend > src > main > resources > i18n`.
 
-<https://angular.io/guide/i18n>
+This will allow any piece of static text in the application to be modified dynamically.
 
-Angular allows any piece of text in an HTML template to be included in the
-translation source file.
+## Usage
+
+In the UI code, there are three options for converting the text provided into translated text.
+
+* Component: `<translate-i18n key="action.foo">Foo</translate-i18n>`
+* Directive: `<label for="foo" translate="label.foo">Foo</label>`
+* Pipe: `{{ action.foo | translate }}`
+
+In addition, the `application.yml` file is an example of a file where dynamic values from the server, can be populated with an i18n identifier for translation. The json files used to generate the metadata wizards also make use of these identifiers and can be translated. They all use the same `messages.properties` files.
+
+Here is an example of the identifers and text found in the `messages.properties` files.
+
+```
+action.cancel=Cancel
+action.save=Save
+action.delete-type=Delete { type }
+```
+
+The `action.delete-type=Delete { type }` example shows how dynamic text can be inserted into the translation as well. These values are determined by the application and are populated at runtime based on user interaction. Many of these values can be translated separately.
 
 ## Conventions
 
@@ -18,7 +34,7 @@ To allow for easier identification of relevant strings the identifiers are
 provided in the following format
 
 ```
-type--kebab-case-text
+type.kebab-case-text
 ```
 
 For example
@@ -26,7 +42,7 @@ For example
 ```html
 <button>example text</button>
 <!-- would become -->
-<button i18n="@@action--example-text">example text</button>
+<button translate="action.example-text">example text</button>
 ```
 
 Where `type` is one of the provided types listed in [the types section](#types)
@@ -42,15 +58,17 @@ The following types are provided:
 
 * `action` buttons or links that cause a state change within the app
 * `label` label for an input or a section
-* `warning` messages that warn a user of exceptions in interactions, i.e.
+* `message` messages that warn a user of exceptions in interactions, i.e.
   validation messages
+* `value` text for displaying values such as `true` or `false`
+* `branding.*` this special type is used to denote the customizable values located in the `ui > brand.ts` file
 
 ### Localize Text Only
 
 ```html
 <!-- BAD -->
 <!-- this will pull both the text AND the icon into the translation -->
-<button i18n="@@action--some-text">
+<button i18n="action.some-text">
   some text
   <i class="fa fa-icon"></i>
 </span>
@@ -59,7 +77,7 @@ The following types are provided:
 <!-- this will only localize the text -->
 <!-- NOTE: ng-container does not create any new dom on the page -->
 <button>
-  <ng-container i18n="@@action--some-text">some text</ng-container>
+  <translate key="action.some-text">some text</ng-container>
   <i class="fa fa-icon"></i>
 </button>
 ```
@@ -71,9 +89,9 @@ When updating text, update the identifier to match the new text field.
 ```html
 <!-- BAD -->
 <!-- identifier does not match text after update -->
-<label i18n="@@label--name">Address</label>
+<label translate="label.name">Address</label>
 
 <!-- GOOD -->
 <!-- identifier and text match -->
-<label i18n="@@label--address">Address</label>
+<label translate="label.address">Address</label>
 ```
diff --git a/ui/README.md b/ui/README.md
index 0e52b0fc9..5e86acade 100644
--- a/ui/README.md
+++ b/ui/README.md
@@ -78,17 +78,6 @@ change to...
     header: 'Metadata Management'
 };`
 
-### Sitewide text
-Finally, this project has support for internationalization (i18n). In the folder `backend > src > main > resources > i18n` folder there is a group of files which can be used to modify the text seen throughout the application. In order to change the default value, you can override the text in the messages_en file with the desired text.
-
-For example:
-
-`action.logout=Logout`
-
-change to...
-
-`action.logout=Sign Out`
-
 
 # Development