docs: Various updates to the i18n documentation based on recent work

Update the documentation with the latest knowledge and workflow based on
how we actually ended up doing the Spanish translation.

Signed-off-by: Philip Withnall <[email protected]>

Author: pwithnall

docs/i18n.md

@@ -15,6 +15,7 @@ which covers the backend of kolibri-explore-plugin.
 At a high level, translatable strings are extracted from Python, JavaScript and
 Vue files, and are collated into several files:
  * `kolibri_explore_plugin/locale/en/LC_MESSAGES/django.po`
+ * `kolibri_explore_plugin/locale/en/LC_MESSAGES/ek-components-messages.csv`
  * `kolibri_explore_plugin/locale/en/LC_MESSAGES/kolibri_explore_plugin-messages.csv`
  * `kolibri_explore_plugin/locale/en/LC_MESSAGES/template-ui-messages.csv`
 
@@ -23,60 +24,69 @@ This extraction process is done by running `yarn i18n-extract`.
 They are in several files because they are extracted from the Django backend and
 the different node frontend modules separately.
 
-These files are checked into git, even though they are generated mechanically
-from the source code, so that translators or external translation tools can pick
-them up at any time, without having to run kolibri-tools on the code.
+Translations are done (currently manually) on the strings in the CSV files, to
+produce JSON files for each locale. A translation workflow which has worked in
+the past is to import the CSV files into Google Docs, translate them
+collaboratively, download the results as CSV files (being careful with the
+column headers; see commit e7819e3d3d1747632253fe683bb876970955d40b), then run
+`yarn i18n-download-translations` to convert the translated CSV files to JSON.
 
-Translations are done (currently manually), and the results committed to git as:
+For this to work, each CSV file must contain `Identifier` and `Translation`
+columns, named exactly that. It may contain other columns (they are ignored),
+and the filename may be anything ending in `.csv`.
+
+**Note:** Currently the translated strings from the
+`ek-components-messages.json` and `template-ui-messages.json` files must also be
+copied into `kolibri_explore_plugin.app-messages.json` in all locales. (For
+example, see commit 8ae264cb83d3b7d5fa19effb82e9772a49f9c751.) This is because
+Kolibri only automatically loads `kolibri_explore_plugin.app-messages.json` in
+webpack.
+
+The results are committed to git as:
  * `kolibri_explore_plugin/locale/${locale}/LC_MESSAGES/django.po`
+ * `kolibri_explore_plugin/locale/en/LC_MESSAGES/ek-components-messages.json`
  * `kolibri_explore_plugin/locale/${locale}/LC_MESSAGES/kolibri_explore_plugin.app-messages.json`
  * `kolibri_explore_plugin/locale/${locale}/LC_MESSAGES/template-ui-messages.json`
 
-CSV versions of the JSON files are also available for review. The CSV versions
-may be imported into Google Docs, collaboratively translated, and then downloaded
-again; the following step will automatically convert them back to JSON.
-
 The translated files for Django now need to be compiled to a machine readable
-form. This is done by `yarn i18n-download-translations`. (The naming is because,
-in Kolibri, this step downloads updated translations from a translation website
-before compiling them --- we do not currently do that in kolibri-explore-plugin.)
+form. This is also done by `yarn i18n-download-translations`. (The naming is
+because, in Kolibri, this step downloads updated translations from a translation
+website before compiling them — we do not currently do that in
+kolibri-explore-plugin.)
 
 It compiles the Django messages to the following file:
  * `kolibri_explore_plugin/locale/${locale}/LC_MESSAGES/django.mo`
 
 This is loaded by Django to provide backend translations.
 
-Secondly, it converts any local CSV files (`kolibri_explore_plugin/locale/${locale}/LC_MESSAGES/*.csv`
-to JSON files, allowing for translation to be done in Google Docs via the CSV.
-For this to work, the CSV file must contain `Identifier` and `Translation`
-columns, named exactly that. It may contain other columns (they are ignored),
-and the filename may be anything ending in `.csv`.
-
 It also generates the following two files, which contain information about the
 locale (such as its name and currency and date formats). They are for use with
 the node [`intl`](https://www.npmjs.com/package/intl) and
 [`vue-intl`](https://www.npmjs.com/package/vue-intl) packages:
  * `kolibri_explore_plugin/assets/src/intl-locale-data.js`
  * `kolibri_explore_plugin/assets/src/vue-intl-locale-data.js`
 
-The frontend loads the installed source JSON files (such as
-`kolibri_explore_plugin/locale/${locale}/LC_MESSAGES/kolibri_explore_plugin.app-messages.json`)
-at runtime. It does this by looking for them using a well-known name in
+The frontend loads the installed source JSON file
+(`kolibri_explore_plugin/locale/${locale}/LC_MESSAGES/kolibri_explore_plugin.app-messages.json`)
+at runtime. It does this by looking for it using a well-known name in
 `LOCALE_PATHS`, then the `WebpackBundleHook.frontend_messages()` function
-injects the contents of the JSON files into the frontend JavaScript with a call
-to `kolibriCoreAppGlobal.registerLanguageAssets()` to register them with the
-translation functions.
+injects the contents of the JSON file into the frontend JavaScript with a call
+to `kolibriCoreAppGlobal.registerLanguageAssets()` to register it with the
+translation functions. The frontend will not load other JSON files, such as
+`template-ui-messages.json`.
 
 Configuration
 ---
 
 Internationalisation configuration is in two places:
  * `kolibri_explore_plugin/locale/language_info.json`
- * `setup.cfg`
+ * `pyproject.toml`/`setup.cfg`
 
 The JSON file contains the list of languages which we want kolibri-explore-plugin
 translated to. It’s in a format needed by kolibri-tools documented
 [here](https://kolibri-dev.readthedocs.io/en/develop/i18n.html#adding-a-newly-supported-language).
 
-`setup.cfg` is needed to point kolibri-tools at the right directories for
-extracting and compiling translatable strings.
+`pyproject.toml` is needed to point kolibri-tools at the right directories for
+extracting and compiling translatable strings. Older versions of kolibri-tools
+looked at `setup.cfg` for the same information; we are porting to
+`pyproject.toml` though.