5 files changed, 49 insertions, 16 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
 
diff --git a/gui/scripts/extract-geo-data.py b/gui/scripts/extract-geo-data.py
index e64cb68867..3b3f97708b 100644
--- a/gui/scripts/extract-geo-data.py
+++ b/gui/scripts/extract-geo-data.py
@@ -1,3 +1,5 @@
+#!/usr/bin/env python3
+
 """
 This module forms a geo json of highly populated cities in the world
 """
diff --git a/gui/scripts/integrate-into-app.py b/gui/scripts/integrate-into-app.py
index 28137a2732..910193fd36 100644
--- a/gui/scripts/integrate-into-app.py
+++ b/gui/scripts/integrate-into-app.py
@@ -1,3 +1,5 @@
+#!/usr/bin/env python3
+
 """
 A helper script to integrate the generated geo data into the app.
 """
diff --git a/gui/scripts/requirements.txt b/gui/scripts/requirements.txt
index 2624dd6b14..6c17c2cd87 100644
--- a/gui/scripts/requirements.txt
+++ b/gui/scripts/requirements.txt
@@ -24,7 +24,12 @@ CairoSVG==2.4.2 \
     --hash=sha256:4e668f96653326780036ebb0a9ff2bb59a8443d7bcfc51a14aab77b57a8e67ad \
     --hash=sha256:9cb1df7e9bc60f75fb87f67940a8fb805aad544337a67a40b67c05cfe33711a2
 cffi==1.13.0 \
-    --hash=sha256:8fe230f612c18af1df6f348d02d682fe2c28ca0a6c3856c99599cdacae7cf226
+    --hash=sha256:1b9ab50c74e075bd2ae489853c5f7f592160b379df53b7f72befcbe145475a36 \
+    --hash=sha256:2eff642fbc9877a6449026ad66bf37c73bf4232505fb557168ba5c502f95999b \
+    --hash=sha256:5ed40760976f6b8613d4a0db5e423673ca162d4ed6c9ed92d1f4e58a47ee01b5 \
+    --hash=sha256:719537b4c5cd5218f0f47826dd705fb7a21d83824920088c4214794457113f3f \
+    --hash=sha256:8fe230f612c18af1df6f348d02d682fe2c28ca0a6c3856c99599cdacae7cf226 \
+    --hash=sha256:dd308802beb4b2961af8f037becbdf01a1e85009fdfc14088614c1b3c383fae5
 click==7.0 \
     --hash=sha256:2335065e6395b9e67ca716de5f7526736bfa6ceead690adf616d925bdc622b13 \
     --hash=sha256:5b94b49521f6456670fdb30cd82a4eca9412788a93fa6dd6df72c94d5a8ff2d7