Issue 2625 - [cms] Crowdin synchronisation script

README.md

 # CMS #
 
 We use this CMS for [adblockplus.org](https://github.com/adblockplus/web.adblockplus.org/)
 and related websites. It converts a directory with content data into static
 files. You are free to use it for other projects but please keep in mind that we
 make no stability guarantees whatsoever and might change functionality any time.
 
 ## How to use ##
 
 ### Running the test server ###
@@ skipping 55 matching lines @@
   [downloaded as ZIP file](https://github.com/adblockplus/cms/archive/master.zip)
   or cloned via `git clone https://github.com/adblockplus/cms.git`)
 
 Run the following command from the directory of the `cms` repository:
 
     python -m cms.bin.generate_static_pages www_directory target_directory
 
 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
 considered:
 
 * `filters`: Custom Jinja2 filters
 * `globals`: Custom Jinja2 global functions and variables
 * `includes`: Various include files
 * `locales`: Localization files
 * `pages`: User-visible pages
 * `static`: Static content
 * `templates`: Page layout templates
 
 There should also be a `settings.ini` file with configuration.
 
 All of these are explained in more detail below.
 
 ### Configuration (settings.ini) ###
 
 The following sections can be defined in `settings.ini`:
 
 * `[general]`: following settings should be listed here:
   * `defaultlocale`: The fallback locale, to be used whenever no localized
     page/strings can be found for a locale.
   * `defaultpage`: the default page which is displayed by the server if the URL
     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.
   The values of the settings are ignored.
 * `[locale_overrides]`: every entry defines that a page should use a different
   locale file, not the one matching its name (to be used when multiple pages
   share localization data).
 
 ### Localization files ###
 
@@ skipping 132 matching lines @@
 filter is invoked. For more information on Jinja2 filters see
 [official documentation](http://jinja.pocoo.org/docs/dev/api/#writing-filters).
 
 ### Custom functions and variables ###
 
 The `globals` directory can define custom Jinja2 globals which will be available
 in all Jinja2 templates. Typically, this is used for custom functions. The file
 name should match the name of the function or variable to be defined, and export
 a variable with that name. E.g. `globals/myfunction.py` can define a function
 called `myfunction` that will become available to all Jinja2 templates.