1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
## Command line actions and their arguments
Trubar is invoked by
`trubar <common-arguments> <action> <arguments>`
**Common arguments** are
`-h`
: Prints help and exits.
`--conf <conf-file>`
: Specifies the [configuration file](../configuration). If not given, Trubar searches for `.trubarconfig.yaml` and `trubar-config.yaml` in current directory, directory with messages, and in source directory (for `collect` and `translate`).
Action must be one of the following:
- **collect:** collects strings from the specified source tree,
- **translate:** copies the source tree and replaces strings with their translations,
- **missing:** prepares a file that contains untranslated messages from another message file (i.e., those with `null` translations),
- **merge:** inserts translations from one message file into another,
- **template:** uses translations into one language to prepare a template for another,
- **stat:** reports on the number of type of translations.
### Collect
```
trubar collect [-h] [-p pattern] [-r removed-translations] [-q] [-n]
-s source-dir messages
```
Collects strings from the specified source tree, skipping files that don't end with `.py` or whose path includes `tests/test_`. (The latter can be changed in [configuration file](../configuration).) Strings with no effect are ignored; this is aimed at docstrings, but will also skip any other unused strings.
If the output file already exists, it is updated: new messages are merged into it, existing translations are kept, and obsolete messages are removed. The latter can be recorded using the option `-r`.
`messages`
: The name of the file with messages (preferrably .jaml). If the file does not exist, it is created, otherwise it is updated with new messages and obsolete
messages are removed.
`-s <path>`, `--source <path>`
: Defines the root directory of the source tree.
`-p <pattern>`, `--pattern <pattern>`
: Gives a pattern that the file path must include to be considered. The pattern is checked against the entire path; e.g. `-p rm/pi` would match the path `farm/pigs.py:`.
`-u`, `--newer`
: Only consider source files that are newer than the message file (if it exists).
`-r <removed-translations>`, `--removed <removed-translations>`
: The name of the file for messages that were present in the messages file but no longer needed. If omitted, removed translations, if any, are saved to file `removed-from-<messages>`, where message is the name of the message file. If the file already exists `(<n>)` is appended to the name.
`-n`, `--dry-run`: Run, but do not change the output file. The file with removed messages is still written.
`-q`, `--quiet`
: Supresses the output, except critical error messages.
### Translate
```
trubar translate [-h] [-p pattern] [--static static-files-dir]
[-q] [-v {0,1,2,3}] [-n]
-s source-dir -d destination-dir messages
```
Translates files with extension .py and writes them to destination directories, and copies all other files. Alternatively, `-i` can be given for translation in-place. Untranslated strings (marked `null`, `false` or `true`) are kept as they are. The action overwrites any existing files.
`messages`
: the name of the file with translated messages.
`-s <source-dir>`, `--source <source-dir>`
: Root directory of the source tree.
`-d <dest-path>`, `--dest <dest-path>`
: Destination directory. Either this option or `-i` is required.
`-i`, `--inplace`
: In-place translation. Either this or `-d` is required.
`-p <pattern>`, `--pattern <pattern>`
: A pattern that the file path must include to be considered.
`--static <static-files-path>`
: Copies the file from the given path into destination tree; essentially `cp -R <static-files-path> <dest-path>/<static-file-path>`. This is used, for instance, for [adding modules with target-language related features](../localization/#plural-forms), like those for plural forms. This option can be given multiple times. If given, this argument overrides `static-files` from config file.
`-q`, `--quiet`
: Supresses output messages, except for critical. Overrides option `-v`.
`-v <level>`, `--verbosity <level>`
: Sets the verbosity level to `0` (critical messages, equivalent to `-q`), `1` (report on files that are created or updated), `2` (also list files that have not changed) or `3` (report on all files, including those merely copied). This option is ignored in presence of `-q`.
`-n`, `--dry-run`
: Run, but do not write anything.
### Merge
```
trubar merge [-h] [-o output-file] [-u unused] [-p pattern] [-n]
translations messages
```
Merges translations into message file.
`translations` (required)
: The "source" file with translations.
`messages` (required)
: File with messages into which the translations from `translations` are merged. This file is modified unless another output file is given.
`-o <output-file>`, `--output <output-file>`
: The output file name; if omitted, the file given as `destination` is changed.
`-u <unused>`, `--unused <unused>`
: A name of the file for messages that no longer appear in the sources.
`-p <pattern>`, `--pattern <pattern>`
: A pattern that the file path must include to be considered.
`-n`, `--dry-run`
: Run, but do not write anything.
### Missing
```
trubar missing [-h] [-p pattern] [-m all-messages] -o output-file
messages
```
Prepare a file with missing translations. A translation is missing if the translated message is `null`. Alternatively, the user can pass a file with all messages (option `-m`), and the translation is missing if the translated file either does not include it or has a `null` translation.
`messages` (required)
: The name of the file with messages.
`-o <output-file>`, `--output <output-file>` (required)
: The name of the output file.
`-m <msg-file>`, `--all-messages <msg-file>`
: If given, this file is considered to contain all messages.
`-p <pattern>`, `--pattern <pattern>`
: If given, the output file will only contain messages from source files whose paths include the pattern.
### Template
```
trubar template [-h] [-p pattern] -o output-file messages
```
Create a template from existing translations. The output file will contain all strings that need attention.
- Strings that are "translated" to `false` are skipped, because they must not be translated.
- Strings that are "translated" to `true` are retained as they are. `true` indicates that they should probably be kept, but may also be translated if needed.
- If string is translated, the original is kept, but translation is replaced by `null`.
- Strings that are not translated (`null`) are kept.
`messages` (required)
: Existing (preferrably complete) translations into some language.
`-o <output-file`, `--output <output-file>` (required)
: Output file name.
`-p <pattern>`, `--pattern <pattern>`
: If given, the output file will only contain messages from source files whose paths include the pattern.
### Stat
```
trubar stat [-h] [-p pattern] messages
```
Print statistics about messages in the given file.
Here's an example output.
`messages`
: File with messages.
`-p <pattern>`, `--pattern <pattern>`
: If given, the count will include files whose paths include the pattern.
```
Total messages: 11161
Translated: 3257 29.2%
Kept unchanged: 313 2.8%
Programmatic: 7065 63.3%
Total completed: 10635 95.3%
Untranslated: 526 4.7%
```
Translated messages are those with actual translations, unchanged are translated as `true` and "programmatic" as `false`. "Untranslated" messages are those that are still marked as `null` and require translations.
|
