Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Delta Between Two Patch Sets: docs/usage/xml-sync.md

Issue 29886648: Issue #6942 - Add XTM integration in CMS (Closed)
Left Patch Set: Addressed initial comments Created Sept. 25, 2018, 12:24 p.m.
Right Patch Set: Addressed comments from Patch Set #4 Created Oct. 5, 2018, 4:23 p.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
Right: Side by side diff | Download
LEFTRIGHT
(no file at all)
1 # XTM Integration
2
3 The integration with the XTM API can be run using the following command:
4
5 python -m cms.bin.xtm_translations [-h] [-v] {login,create,upload,download}
6
7
8 and it has four main operational modes:
9
10
11 ## 1. XTM Login
12
13 This mode prompts the user for the login credentials and prompts
14 the API for the authentication token. This token should then be saved as an
15 environment variable to be used in the other modes. It can be run as follows:
16
17
18 python -m cms.bin.xtm_translations [-h] [-v] login [-h]
19
20
21
22 ## 2. Project Creation
23
24 In this mode, one can create an XTM project. It can be run as follows:
25
26
27 python -m cms.bin.xtm_translations [-h] [-v] create [-h] --name NAME
28 --desc DESC --client-id CLIENT_ID --ref-id REF_ID
29 --workflow-id WORKFLOW_ID [--source-lang SOURCE_LANG]
30 [--save-id] [source_dir]
31
32
33 where:
34 * --name* = The name of the project will have once created.
35 * *--desc** = The description you wish to add to the project.
36 * *--client-id** = The id of the **pre-configured** XTM client you want
37 associated with the project. Has to be an integer!
38 * *--ref-id** = The reference id you want associated with the XTM project.
39 * *--workflow-id** = The id of the **pre-configured** XTM workflow to be
40 associated with the project. Has to be an integer!
41 * *--source-lang* = The language of the source files. If not provided,
wspee 2018/10/10 15:09:16 This parameter is not mandatory
42 the script will use `en_US` by default.
43 * *--save-id* = Whether to save the id of the newly created project into
wspee 2018/10/10 15:09:16 This parameter is not mandatory
44 'settings.ini' or not.
45 * *source_dir* = The source directory of the website. If not specified, the
46 script would consider the current working directory as the source for the websit e.
47 It will be used to extract all the translation strings and create the files
48 to be uploaded on project creation. It will also be used to automatically
49 detect the target languages for this specific project.
50
51 **Note:** All arguments marked with * are **mandatory** and the script will
52 fail if not provided.
53
54 In order for this mode to work, it requires the XTM authentication token
55 to be saved in the `XTM_TOKEN` environment variable.
56
57
58 ## 3. File Uploading
59
60 This mode can be used to upload new files for translation to an existing project .
61 It can be run as follows:
62
63
64 python -m cms.bin.xtm_translations [-h] [-v] upload [-h] [--no-overwrite]
wspee 2018/10/10 15:09:15 Also it might make sense to document the settings.
wspee 2018/10/10 15:09:15 For a per issue workflow (and also in general) it
65 [source_dir]
66
67
68 where:
69 * *--no-overwrite* = If this flag is set, then the script would **create new
70 files** in XTM, instead of overwriting the ones that were already there.
71 * *source_dir* = The source directory of the website. See above for the full
72 explanation.
73
74 If you wish to add a new target language to the project automatically,
75 simply create a corresponding directory in the website's `locales` directory
76 and the script will update the XTM project accordingly before uploading the
77 new files and will create jobs for the new languages as well.
78
79 In order for this mode to work, it requires two things to be present:
80 1. The XTM authentication token saved in the `XTM_TOKEN` environment variable.
81 2. The XTM project number present in `settings.ini`, under the `project_id`
82 option, in the `XTM` section.
83
84
85 ## 4. Translation Files Downloading
86
87 This mode downloads the translation files from the XTM project and saves them
88 in the website's `locales` directory. It can be run as follows:
89
90 python -m cms.bin.xtm_translations [-h] [-v] download [-h] [source_dir]
91
92
93 where `source_dir` is the source directory of the website. See above for full
94 explanation.
95
96 When run in this mode, the script will remove all the translation files that
97 were previously saved locally and then save the new ones in their place.
98
99 In order for this mode to work, three requirements need to be fulfilled:
100 1. The XTM authentication token saved in the `XTM_TOKEN` environment variable.
101 2. The XTM project number present in `settings.ini`, under the `project_id`
102 option, in the `XTM` section.
103 3. (At least one) translation file(s) to be present in XTM.
104
105
106 ## Dependencies
107
108 On top of the Python standard library, this script requires the following
109 additional libraries to run correctly:
110
111 1. [Markdown](https://pypi.org/project/Markdown/)
112 2. [Jinja2](https://pypi.org/project/Jinja2/)
113 3. [Requests](https://pypi.org/project/requests/)
LEFTRIGHT

Powered by Google App Engine
This is Rietveld