tweaked locale selection & added i18n technical documentation

4 files changed, 49 insertions, 3 deletions

diff --git a/README.md b/README.md
index ff746922..738b0a81 100644
--- a/README.md
+++ b/README.md
@@ -12,4 +12,4 @@ to get started clone the repo and run `pnpm install`, then `pnpm run dev` to get
 
 ## Internationalization
 
-CoinOS has a system for translation using [`svelte-i18n`](https://www.npmjs.com/package/svelte-i18n).  For more information and instructions on how to translate CoinOS, click [here](./doc/i18n.md).
+CoinOS has a system for translation using [`svelte-i18n`](https://www.npmjs.com/package/svelte-i18n).  For more information and instructions on how to translate CoinOS, click [here](./doc/i18n.md).  For technical details, click [here](./doc/i18n-technical.md).
diff --git a/doc/i18n-technical.md b/doc/i18n-technical.md
new file mode 100644
index 00000000..ea28627e
--- /dev/null
+++ b/doc/i18n-technical.md
@@ -0,0 +1,46 @@
+# CoinOS Internationalization - Technical Information
+
+*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
+
+## 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.
+
+## Internationalization Code
+
+The main code for CoinOS's internationalization is at `src/lib/i18n.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`.
+
+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`.
+
+## Locale Files
+
+Each locale in `coinos-ui-v2` is defined by a JSON file in `src/locales`.  Its name is the locale's [ISO 639-1 code](https://en.wikipedia.org/wiki/ISO_639-1) plus `.json`.  It is simply a file that maps string IDs to translated strings.  Here is an example of `en.json`:
+
+```json
+{
+  "howItWorks": "How It Works",
+  "faq": "FAQ",
+  "about": "About",
+  "startInSeconds": "Start in Seconds",
+  "signIn": "Sign In"
+}
+```
+
+## 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:
+
+```
+{$_('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.
diff --git a/doc/i18n.md b/doc/i18n.md
index b8727524..b1cbd78e 100644
--- a/doc/i18n.md
+++ b/doc/i18n.md
@@ -2,7 +2,7 @@
 
 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:
 
-*NOTE: This guide was written for people without a technical background.*
+*NOTE: This guide was written for people without a technical background.  If you want more technical details, click [here](./i18n-technical.md)*
 
 ## Required Background Knowledge
 
diff --git a/src/lib/i18n.js b/src/lib/i18n.js
index 44d06287..fdf5de3c 100644
--- a/src/lib/i18n.js
+++ b/src/lib/i18n.js
@@ -35,7 +35,7 @@ function pickLocale(navigatorLocale, availableLocales) {
   } else if (availableLocales.includes(languageCode)) {
     return languageCode;
   } else {
-    return null;
+    return navigatorLocale;
   }
 }