updated i18n manual for new translation format & added more info

1 files changed, 44 insertions, 11 deletions

diff --git a/doc/i18n.md b/doc/i18n.md
index 5bbd049b..2eccc7e4 100644
--- a/doc/i18n.md
+++ b/doc/i18n.md
@@ -1,14 +1,16 @@
 # CoinOS Internationalization
 
-CoinOS can be translated into other languages by editing JSON files. You do not need programming knowledge to do this, or to use these instructions. Here are instructions on how to internationalize CoinOS:
+CoinOS can be translated into other languages by editing [JSON](https://www.json.org/json-en.html) files. You do not need programming knowledge to do this, or to use these instructions. Here are instructions on how to translate CoinOS:
 
 _NOTE: This guide was written for people without a technical background. If you want more technical details, click [here](./i18n-technical.md)._
 
+Last Updated: 2022-08-23
+
 ## Required Background Knowledge
 
 ### Language Codes
 
-Before you can translate CoinOS, you need to know the [ISO 639-1 code](https://en.wikipedia.org/wiki/ISO_639-1) of your language. This is a standard two-letter code that your browser uses to refer to a language (for example, English is `en`, and French is `fr`). You can also add a dash and more letters to refer to a specific region (for example, American English is `en-US`, and British English is `en-GB`). A list of all codes can be found [here](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes), and Firefox-based browsers show you the code when you are selecting your browser's language.
+Before you can translate CoinOS, you need to know the [ISO 639-1 code](https://en.wikipedia.org/wiki/ISO_639-1) of your language. This is a standard two-letter code that your browser uses to refer to a language (for example, English is `en`, and Spanish is `es`). You can also add a dash and more letters to refer to a specific region (for example, American English is `en-US`, and British English is `en-GB`). A list of all codes can be found [here](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes), and Firefox-based browsers show you the code when you are selecting your browser's language.
 
 ### Locale Files
 
@@ -28,15 +30,47 @@ Each line (other than the opening and closing braces) contains a **text name**,
 
 ### The Language List
 
-At the top of the file `src/lib/i18n.js`, there is a list of translations that looks something like this:
+There is also a JSON file that controls which languages are understood.  It is at `src/lib/translations/lang.json` and looks something like this:
+
+```JSON
+{
+  "en": "English",
+  "fr": "Français",
+  "es": "Español"
+}
+```
+
+This file simply maps each language to its name.  It is used both to get a list of languages and to get the name of each language for the language selector.  If a translation is not in this file, CoinOS will not be able to see it.
+
+### JSON Sections
+
+You might notice that some of the left-text in the language files don't have a string after them, instead having some `{}` curly brackets, like in this example:
 
-```js
-// The list of locales to look for
-// ADD ALL NEW LANGUAGE CODES TO THIS LIST
-const localeCodes = ['en', 'fr'];
+```JSON
+"nav": {
+  "startInSeconds": "Start in Seconds",
+  "account": "Account",
+  "signIn": "Sign In",
+  "signOut": "Sign Out",
+  "dashboard": "Dashboard",
+  "settings": "Settings",
+  "support": "Support"
+},
 ```
 
-In order for a translation to be recognized by the CoinOS system, you need to add it to this list. At the end of the list, before the second square bracket, add a comma, then a space, then the language code in quotation marks.
+These denote sections of the JSON file, which helps keep it organized.  If you're translating a string that is in a section, make sure the translated string is in the same section of the new file.  If that section doesn't exist, just create it.
+
+### HTML Tags
+
+Sometimes, you will see strange text surrounded with `<>` angle brackets.  Every one of these "HTML tags" will be followed by another one starting with a slash.  Here's an example:
+
+```JSON
+"p1": "<strong>CoinOS</strong> is an <strong>open source</strong> bitcoin web wallet, point of sale, ecommerce marketplace and exchange platform. Development started in Vancouver in September 2012 as a way to provide local merchants with a convenient way to accept bitcoin payments.",
+```
+
+These apply a certain style to the text between them.  For example, the tags above will make "CoinOS" and "open source" bold, leaving the rest non-bold.
+
+When translating strings containing tags, don't change the tags.  Do translate the text between them, and don't be afraid to move them around - just make sure they contain the same part of the sentence, and that the one without the slash is always before the one with the slash.  Not all of the localizable strings support HTML tags, so you shouldn't use them if they aren't in the original string you're translating.
 
 ## Creating a New Translation
 
@@ -50,9 +84,8 @@ Follow these steps to create a new translation. You will need a GitHub account t
    _NOTE: "CoinOS" is a feminine noun in languages with grammatical gender._
    ![Translating in GitHub](./img/translate_github.png)
 5. Scroll down and use the green button to commit the file.
-6. Go to the `src` folder again, then `lib`, then `i18n.js`.
-7. Use the pencil icon on the top-right to edit the file, then add your language code (**in quotation marks**) to the list.
-   ![Adding a new translation in GitHub](./img/add_locale_github.png)
+6. Go to the `src` folder again, then `lib`, then `translations`, then `lang.json`.
+7. Use the pencil icon on the top-right to edit the file, then add a new line containing your language code in quotes, followed by a colon, followed by the full name of your language in quotes.  Make sure every line except the last has a comma at the end.
 8. Commit your changes like you did in step 5.
 
 ## Adding to an Existing Translation