Issue 2625 - [cms] Crowdin synchronisation script

README.md

Index: README.md
diff --git a/README.md b/README.md
index c9a43a7db2d0348d82b8226d9499b65195ea030d..113b56983c0cd77b8aebbcc07acc4988606699d3 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,42 @@ Run the following command from the directory of the `cms` repository:
 Here `www_directory` should be replaced by the path to your content directory.
 `target_directory` is the path where static files will be placed..
 
+### Syncing translations ###
+
+Before syncing translations ensure the following:
+
+- The `crowdin-project-name` setting has been set in the site's configuration.
+- The `urllib3` Python module is installed.
+
+Now to sync with Crowdin type the following:
+
+    python -m cms.bin.translate www_directory crowdin_project_api_key [logging_level]
+
+The script might take a while to run, it does the following things:
+
+1. Requests information about your Crowdin project
+2. Checks all local locales are supported by Crowdin and enabled for your project
+3. Renders all pages in your default language and extracts all page strings
+4. Creates any required directories in your Crowdin project
+5. Uploads any new page strings and updates any existing page strings
+6. Uploads any pre-existing translation files for any newly uploaded pages
+7. Requests Crowdin generate a fresh translations export archive
+8. Downloads the archive of translations and extracts it replacing all local
+   translation files
+
+Notes:
+
+- You have to use the Crowdin project's API key, not your account API key
+- You should probably enable "Skip untranslated strings" under your
+  project settings.
+- Translations are only _uploaded_ for new files. If you are syncing with
+  Crowdin for the first time, and you have existing translation files pay
+  attention to any warnings. If there are any problems it is recommended
+  you re-create another fresh Crowdin project and try again. (Otherwise
+  translations for the pages already uploaded could be lost!)
+- If you are running the script from a cronjob or similar you will probably
+  want to set the logging level to `ERROR` or similar
+
 ## Content structure ##
 
 Currently, the following directories of your content directory will be
@@ -101,6 +137,9 @@ The following sections can be defined in `settings.ini`:
     doesn't contain a page name. Note that while the test server will consider
     that setting automatically, the real server might need to be configured
     accordingly.
+  * `crowdin-project-name`: The Crowdin project name, this must be set for if
+    you intend to use the cms.bin.translate script to update the Crowdin
+    translations.
 * `[langnames]`: defines the language names correspoding to particular language
   codes.
 * `[rtl]`: any language codes listed here are treated as right-to-left languages.