Merge branch 'master' of github.com:coinos/coinos-ui-v2

2 files changed, 84 insertions, 21 deletions

diff --git a/doc/i18n-technical.md b/doc/i18n-technical.md
index a0d64938..46fbb094 100644
--- a/doc/i18n-technical.md
+++ b/doc/i18n-technical.md
@@ -2,21 +2,20 @@
 
 _NOTE: This documentation was written for people with a technical background. If you do not have a technical background, consider reading [this guide](./i18n.md) instead._
 
-Last Updated: 2022-08-08
+Last Updated: 2022-08-23
 
 ## Dependencies
 
-CoinOS's internationalization system depends on the `npm` package [`svelte-i18n`](https://www.npmjs.com/package/svelte-i18n). Consider reading [its documentation](https://github.com/kaisermann/svelte-i18n/blob/HEAD/docs/Getting%20Started.md) in addition to this.
+CoinOS's internationalization system depends on the `npm` package [`sveltekit-i18n`](https://www.npmjs.com/package/sveltekit-i18n). Consider reading [its documentation](https://github.com/sveltekit-i18n/lib/tree/master/docs/README.md) in addition to this.
 
 ## Internationalization Code
 
-The main code for CoinOS's internationalization is at `src/lib/i18n.js`. When imported, it does the following:
+The main code for CoinOS's internationalization is at `src/lib/translations/index.js`. When imported, it does the following:
 
-1. Load all of the locales [asynchronously](https://github.com/kaisermann/svelte-i18n/blob/main/docs/Getting%20Started.md#32-asynchronous).
-2. Pick a locale intelligently, depending on the available locales and the navigator locale, using `pickLocale`. Specifically, if the user's locale (e.g. `en-US`) isn't available but its non-regional version (e.g. `en`) is, the system will use the non-regional locale.
-3. Initialize `svelte-i18n`.
+1. Load all of the locales asynchronously, based on .
+3. Initialize `sveltekit-i18n`.
 
-It also defines important constants, including the list of available locales and the default locale. This code is loaded by importing `$lib/i18n` in `src/routes/__layout.svelte`.
+It also defines important constants, including the list of available locales and the default locale. This code is loaded by importing `$lib/translations` in `src/routes/+layout.svelte`.  This code, which runs in the frontend, also persists the locale in `localStorage`.
 
 ## Locale Files
 
@@ -34,14 +33,12 @@ Each locale in `coinos-ui-v2` is defined by a JSON file in `src/locales`. Its na
 
 ## Internationalizing Strings
 
-Strings are internationalized by simply using `svelte-i18n`'s [`$format`](https://github.com/kaisermann/svelte-i18n/blob/96a5adab7560249c8881e0612454e01c09273400/docs/Formatting.md) function. A localized string looks like this:
+Strings are internationalized by simply using `sveltekit-i18n`'s `$t` function. A localized string looks like this:
 
 ```
 {$t('stringID')}
 ```
 
-(`$_` is a convenient alias for `$format`.)
-
 ## The Locale Selector
 
 CoinOS also has a `LocaleSelector` component, which should be used to select locales. It is a dropdown that allows you to select & update the locale.
@@ -51,4 +48,5 @@ CoinOS also has a `LocaleSelector` component, which should be used to select loc
 CoinOS has a Python script that helps you with the technical parts of translation. It is located at `src/locales/guided_translation.py`. It also has some utility functions:
 
 - `nested_dict_keys` - gets a list of keys of a nested dictionary in dot-separated shallow format (e.g. a.b.c)
+- `create_locale` - adds a new locale to the lang.json file
 - `localize_string` - localizes a string interactively
diff --git a/doc/i18n.md b/doc/i18n.md
index 5bbd049b..f33ab2de 100644
--- a/doc/i18n.md
+++ b/doc/i18n.md
@@ -1,14 +1,18 @@
 # 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)._
 
+These instructions assume you have a GitHub account and have permission to modify this repository.  If you do not have permission, you will need to [make a fork](https://github.com/coinos/coinos-ui-v2/fork) using the link on the top-right, then follow these instructions to translate your fork, then make a pull request using the link below the "Code" button to apply your changes to the main repository.
+
+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 +32,67 @@ 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:
 
-```js
-// The list of locales to look for
-// ADD ALL NEW LANGUAGE CODES TO THIS LIST
-const localeCodes = ['en', 'fr'];
+```JSON
+{
+  "en": "English",
+  "fr": "Français",
+  "es": "Español"
+}
 ```
 
-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.
+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:
+
+```JSON
+"nav": {
+  "startInSeconds": "Start in Seconds",
+  "account": "Account",
+  "signIn": "Sign In",
+  "signOut": "Sign Out",
+  "dashboard": "Dashboard",
+  "settings": "Settings",
+  "support": "Support"
+},
+```
+
+These denote sections of the JSON file, which helps keep it organized.  If you're translating some text that is in a section, make sure the translated text is in the same section of the new file.  If that section doesn't exist, just create it.
+
+In the translation files, sections roughly correspond to where the the text is in CoinOS.  This can be useful if you need context for some text.  Here are some of these associations (`A.B` means section `B` is located inside `A`):
+
+| Section           | Location                                          |
+|-------------------|---------------------------------------------------|
+| 404               | the 404 page                                      |
+| about             | the 'About' section at the bottom of the homepage |
+| error             | the error page                                    |
+| faq               | the FAQ on the homepage                           |
+| footer            | the bottom of the homepage                        |
+| howItWorks        | the 'How it Works' section                        |
+| invoice           | the Invoice page                                  |
+| jobs              | the Jobs page                                     |
+| landing           | the top of the homepage                           |
+| login             | the Register and Login pages                      |
+| user              | the user page                                     |
+| user.dashboard    | the user's dashboard                              |
+| user.settings     | the settings page                                 |
+| user.support      | the user's support page                           |
+| user.transactions | the user's transaction history page               |
+
+### 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 +106,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
@@ -69,3 +124,13 @@ Follow these steps to add to an existing translation. You will also need a GitHu
    _NOTE: "CoinOS" is a feminine noun in languages with grammatical gender._
 8. Repeat steps 3-7 for every piece of text you want to translate (you should probably open `en.json` in another tab, so that your changes from step 6 aren't erased).
 9. Scroll down and use the green button to commit the file.
+
+## The Guided Translation Script
+
+There is also a program that helps you translate automatically - all you have to do is input the translated text and it will do the rest for you!  You need a bit of technical knowledge to use it however, specifically, you need to know:
+- How to use basic [git](https://git-scm.com/) (cloning, pulling, committing, pushing)
+- How to run a [Python](https://www.python.org/) script
+
+The script also shows you the ID of each bit of text you are translating, so that you can know where it is.  `A.B` means string `B` in section `A`, `A.B.C` means string `C` in subsection `B` in section `A`, etc.
+
+Clone the repository, then use the guided translation script (at `src/locales/guided_translation.py`) to update the translation files.  You will need to pull before running, and commit/push your changes in order for them to be applied to CoinOS.