Update README

2 files changed, 39 insertions, 15 deletions

diff --git a/gui/locales/README.md b/gui/locales/README.md
index 2878916004..41336b2de8 100644
--- a/gui/locales/README.md
+++ b/gui/locales/README.md
@@ -2,26 +2,46 @@ This is a folder with gettext translations for Mullvad VPN app.
 
 ## Adding new translations
 
-Create a new sub-folder under `gui/locales`, use the locale identifier for the
-folder name.
+1. Create a new sub-folder under `gui/locales`, use the locale identifier for the folder name.
+   
+   The complete list of supported locale identifiers can be found at:
+   
+   https://electronjs.org/docs/api/locales
 
-The complete list of supported locale identifiers can be found at:
+1. Add a new language on Crowdin under Settings -> Translations -> Target languages menu. 
+   
+   By default the file structure is configured to produce folders with translations using two-letter
+   language code (defined under Settings -> Files -> <FILE> -> ... [ellipsis] -> Settings). 
+  
+   If you wish to add a dialect (i.e: `pt-BR`), you have to provide a custom mapping 
+   to tell Crowdin to output Portuguese (Brazil) as `pt-BR` instead of `pt`.
+   
+   In order to add a language mapping, go to Settings -> General Settings -> Language mapping 
+   (three faders icon on the left hand side of the "Translations" menu).
 
-https://electronjs.org/docs/api/locales
-
-In order to initialize the translations catalogue for the new locale, simple follow the update
-procedure, described in the section below.
+1. Follow the procedure as described in `gui/scripts/README.md`.
 
+1. Optional: Upload the automatically translated `<NEW_LOCALE>/relay-locations.po` to 
+   Crowdin. 
+   
+   *Note: Replace `<NEW_LOCALE>` with the identifier of a newly added language.*
+   
+   1. ZIP file with the following command:
+   
+      ```
+      cd gui/locales
+      zip payload.zip <NEW_LOCALE>/relay-locations.po
+      ```
+   
+   1. Upload `payload.zip` to Crowdin via web interface (Settings -> Translations -> Upload 
+      translations).
 
 ## Updating translations template
 
 ### messages.pot
 
 Run `npm run update-translations` to extract the new translations from the source
-code and update all of the existing catalogues.
-
-The new translations are automatically added to empty sub-folders using the POT template at
-`gui/locales/messages.pot`. Folders that contain a `.gitkeep` file are ignored.
+code. Use `crowdin.sh upload` to submit them to Crowdin.
 
 ### relay-locations.pot
 
@@ -40,10 +60,14 @@ Triggering Crowdin to start translating has to be done manually. Speak to the pr
 
 ## Downloading translations from Crowdin
 
-Before downloading from Crowdin the project must be "built" through their web interface. When you
-later download you will receive the translations from the last point in time when it was built:
+Before downloading from Crowdin the project must be "built" first. When you
+later download you will receive the translations from the last point in time when it was built.
+
+In order to make a fresh build with translations, use the following command:
 
-Go to the Crowdin project > Settings > "Build & Download" dropdown button > "Build project"
+```
+CROWDIN_API_KEY=$YOUR_CROWDIN_KEY ./gui/scripts/crowdin.sh export
+```
 
 In order to download and integrate the new translations from Crowdin into the app, use the following
 command:
diff --git a/gui/scripts/README.md b/gui/scripts/README.md
index 6d11c55ec0..c60323134a 100644
--- a/gui/scripts/README.md
+++ b/gui/scripts/README.md
@@ -62,7 +62,7 @@ and finally generate the R-Tree cache:
 npx ts-node prepare-rtree.ts
 ```
 
-At this point all of the data should be saved in `gui/geo-data/out` folder.
+At this point all of the data should be saved in `gui/scripts/out` folder.
 
 ## App integration notes