Add a documentation about internationalisation

README.md

@@ -97,7 +97,7 @@ Then run the app with the `flutter run` command above, and a link to the logging
 ## Internationalisation
 
 Do not edit the `app_en.arb` file by hand, this file is generated.
-More information [in the wiki](https://github.com/lichess-org/mobile/wiki/About-internationalisation).
+For more information, see [Internationalisation](./docs/internationalisation.md).
 
 ## Releasing
 

docs/internationalisation.md

@@ -0,0 +1,48 @@
+# Internationalisation
+
+We're using the standard way of internationalising our app, as desbribed in the
+[official documentation)(https://docs.flutter.dev/ui/accessibility-and-internationalization/internationalization#setting-up).
+
+What is specific to this project is the way we produce the template `lib/l10n/app_en.arb` file.
+
+This file is generated by a script: `scripts/update-arb-from-crowdin.mjs` that fetches lichess translations from the [crowdin lichess project](https://crowdin.com/project/lichess).
+
+For now, only translations from the website are fetched. Mobile specific translations are yet to be created in crowdin.
+
+There is a ticket to create a mobile specific project in crowdin: https://github.com/lichess-org/mobile/issues/98
+
+## How to update the translations
+
+There is a script that fetches the translations from crowdin and updates the `lib/l10n/app_en.arb` file.
+
+This file must not be edited manually, as it will be overwritten by the script.
+
+To update the translations, run the following commands:
+
+```bash
+./scripts/update-arb-from-crowdin.mjs
+flutter gen-l10n
+```
+
+If the script does nothing (no changes), it means that the translations from the
+last crowdin export are already up to date.
+
+## How to add a new module from lila
+
+Translations in
+[lila](https://github.com/lichess-org/lila/tree/master/translation/source) are organised by module.
+
+The list of modules we're using in the app is defined in the `scripts/update-arb-from-crowdin.mjs` script.
+
+If you need to add a new module, you need to add it to the list of modules in the script.
+
+Note that a module can contain a lot of translations that we don't need in the app. In this case, you can filter the translations by adding the module to the `whitelist` defined in the script.
+
+Once you've added the module to the script, you can run the script to update the translations.
+
+```bash
+./scripts/update-arb-from-crowdin.mjs
+flutter gen-l10n
+```
+
+You should see the new strings in the `lib/l10n/lila_*.arb` and `lib/l10n/lila_*.dart` files.

scripts/update-arb-from-crowdin.mjs

@@ -23,12 +23,8 @@ const unzipMaxBufferSize = 1024 * 1024 * 10 // Set maxbuffer to 10MB to avoid er
 // selection of lila translation modules to include
 const modules = ['activity', 'contact', 'site', 'patron', 'preferences', 'puzzle', 'puzzleTheme', 'perfStat', 'search', 'settings', 'streamer', 'storm', 'study']
 
-// Order of locales with variants matters: the fallback must always be first
-// eg: 'de-DE' is before 'de-CH'
-// Note that 'en-GB' is omitted here on purpose because it is the locale used in template ARB.
-// This list must be consistent with the `kSupportedLocales` constant defined in `lib/constants.dart`.
-const locales = ['af-ZA', 'ar-SA', 'az-AZ', 'be-BY', 'bg-BG', 'bn-BD', 'br-FR', 'bs-BA', 'ca-ES', 'cs-CZ', 'da-DK', 'de-DE', 'de-CH', 'el-GR', 'en-US', 'eo-UY', 'es-ES', 'et-EE', 'eu-ES', 'fa-IR', 'fi-FI', 'fo-FO', 'fr-FR', 'ga-IE', 'gl-ES', 'he-IL', 'hi-IN', 'hr-HR', 'hu-HU', 'hy-AM', 'id-ID', 'it-IT', 'ja-JP', 'kk-KZ', 'ko-KR', 'lb-LU', 'lt-LT', 'lv-LV', 'mk-MK', 'nb-NO', 'nl-NL', 'nn-NO', 'pl-PL', 'pt-PT', 'pt-BR', 'ro-RO', 'ru-RU', 'sk-SK', 'sl-SI', 'sq-AL', 'sr-SP', 'sv-SE', 'tr-TR', 'tt-RU', 'uk-UA', 'vi-VN', 'zh-CN', 'zh-TW']
-
+// list of keys (per module) to include in the ARB file
+// If a module is not listed here, all keys will be included
 const whiteLists = {
   'patron': ['donate', 'lichessPatron'],
   'contact': ['contact', 'contactLichess'],
@@ -37,6 +33,13 @@ const whiteLists = {
   'study': ['start', 'shareAndExport'],
 }
 
+
+// Order of locales with variants matters: the fallback must always be first
+// eg: 'de-DE' is before 'de-CH'
+// Note that 'en-GB' is omitted here on purpose because it is the locale used in template ARB.
+// This list must be consistent with the `kSupportedLocales` constant defined in `lib/constants.dart`.
+const locales = ['af-ZA', 'ar-SA', 'az-AZ', 'be-BY', 'bg-BG', 'bn-BD', 'br-FR', 'bs-BA', 'ca-ES', 'cs-CZ', 'da-DK', 'de-DE', 'de-CH', 'el-GR', 'en-US', 'eo-UY', 'es-ES', 'et-EE', 'eu-ES', 'fa-IR', 'fi-FI', 'fo-FO', 'fr-FR', 'ga-IE', 'gl-ES', 'he-IL', 'hi-IN', 'hr-HR', 'hu-HU', 'hy-AM', 'id-ID', 'it-IT', 'ja-JP', 'kk-KZ', 'ko-KR', 'lb-LU', 'lt-LT', 'lv-LV', 'mk-MK', 'nb-NO', 'nl-NL', 'nn-NO', 'pl-PL', 'pt-PT', 'pt-BR', 'ro-RO', 'ru-RU', 'sk-SK', 'sl-SI', 'sq-AL', 'sr-SP', 'sv-SE', 'tr-TR', 'tt-RU', 'uk-UA', 'vi-VN', 'zh-CN', 'zh-TW']
+
 async function main() {
   mkdirSync(`${tmpDir}`, {recursive: true})