Issue #6942 - Add XTM integration in CMS

docs/usage/README.md

Index: docs/usage/README.md
diff --git a/docs/usage/README.md b/docs/usage/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..3fd96f6b50ced88950d1a577f0be84dababf0fe7
--- /dev/null
+++ b/docs/usage/README.md
@@ -0,0 +1,101 @@
+#XTM Integration

[Vasily Kuznetsov, 2018/09/26 15:45:25]

Not having space between # and XTM doesn't work with Grip
(https://github.com/joeyespo/grip), which I think uses github renderer, so it
might be better to put it there just to be on the safe side.

[Vasily Kuznetsov, 2018/09/26 15:45:25]

This file should probably not be called README.md but something more specific
line `xml-sync.md` and also linked from the main README.

[Tudor Avram, 2018/10/04 06:48:11]

Done.

[Tudor Avram, 2018/10/04 06:48:11]

Done.

+
+The integration with the XTM API can be run using the following command:
+
+```commandline

[Vasily Kuznetsov, 2018/09/26 15:45:25]

You can also introduce code blocks like this:

Some text text text:

    code, indented by 4 spaces

    some more code

This reads better when you're looking at plaintext. Is there an advantage to
backquotes and commandline type?

[Tudor Avram, 2018/10/04 06:48:11]

Done.

+    python -m cms.bin.xtm_translations [-h] [-v] {login,create,upload,download}
+```
+
+and it has four main operational modes:
+
+
+### 1. XTM Login 
+This mode prompts the user for the login credentials and prompts 
+the API for the authentication token. This token should then be saved as an 
+environment variable to be used in the other modes. It can be run as follows:
+
+```commandline
+    python -m cms.bin.xtm_translations [-h] [-v] login [-h]
+```
+
+
+### 2. Project Creation
+In this mode, one can create an XTM project. It can be run as follows:
+
+```commandline
+    python -m cms.bin.xtm_translations [-h] [-v] create [-h] --name NAME 
+                --desc DESC --client-id CLIENT_ID --ref-id REF_ID 
+                --workflow-id WORKFLOW_ID [--source-lang SOURCE_LANG] 
+                [--save-id] [source_dir]
+```
+
+where:
+* --name* = The name of the project will have once created.
+* *--desc** = The description you wish to add to the project.
+* *--client-id** = The id of the **pre-configured** XTM client you want 
+associated with the project. Has to be an integer!
+* *--ref-id** = The reference id you want associated with the XTM project.
+* *--workflow-id** = The id of the **pre-configured** XTM workflow to be 
+associated with the project. Has to be an integer!
+* *--source-lang* = The language of the source files. If not provided, 
+the script will use `en_US` by default. 
+* *--save-id* = Whether to save the id of the newly created project into 
+'settings.ini' or not.
+* *source_dir* = The source directory of the website. If not specified, the 
+script would consider the current working directory as the source for the website.
+It will be used to extract all the translation strings and create the files 
+to be uploaded on project creation. It will also be used to automatically 
+detect the target languages for this specific project.
+
+**Note:** All arguments marked with * are **mandatory** and the script will
+fail if not provided.
+
+In order for this mode to work, it requires the XTM authentication token
+to be saved in the `XTM_TOKEN` environment variable.
+
+
+### 3. File Uploading
+This mode can be used to upload new files for translation to an existing project.
+It can be run as follows:
+
+```commandline
+    python -m cms.bin.xtm_translations [-h] [-v] upload [-h] [--no-overwrite] 
+                [source_dir]
+```
+
+where:
+* *--no-overwrite* = If this flag is set, then the script would **create new 
+files** in XTM, instead of overwriting the ones that were already there.
+* *source_dir* = The source directory of the website. See above for the full
+explanation.
+
+If you wish to add a new target language to the project automatically, 
+simply create a corresponding directory in the website's `locales` directory
+and the script will update the XTM project accordingly before uploading the
+new files and will create jobs for the new languages as well.
+
+In order for this mode to work, it requires two things to be present:
+1. The XTM authentication token saved in the `XTM_TOKEN` environment variable.
+2. The XTM project number present in `settings.ini`, under the `project_id` 
+option, in the `XTM` section.
+
+
+### 4. Translation Files Downloading
+This mode downloads the translation files from the XTM project and saves them
+in the website's `locales` directory. It can be run as follows:
+
+```commandline
+    python -m cms.bin.xtm_translations [-h] [-v] download [-h] [source_dir]
+```
+
+where `source_dir` is the source directory of the website. See above for full
+explanation.
+
+When run in this mode, the script will remove all the translation files that
+were previously saved locally and then save the new ones in their place.
+
+In order for this mode to work, three requirements need to be fulfilled:
+1. The XTM authentication token saved in the `XTM_TOKEN` environment variable.
+2. The XTM project number present in `settings.ini`, under the `project_id` 
+option, in the `XTM` section.
+3. (At least one) translation file(s) to be present in XTM.