Newer
Older
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
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
[](https://jenkins.dev.l11n.de/job/L11N_Group/job/L11N_Gettext_Plugin/job/main/)
[](https://opensource.org/licenses/Apache-2.0)
## What does this plugin do?
The Gradle Gettext Plugin add functionality to your project, to extract, translate (by you) and compile strings into your wanted format, so you don't have to do this manually.
The amount of tasks will be specified by the amount of SourceSets, which are provided. The tasks will have names like `{type}-{SourceSetName}` for every type of `[xgettext, msginit, msgmerge, msgfmt]`.
Additionally, there will be `{type}-ALL` tasks in the root project, to call all tasks of this type at once.
## Include into your build
As for now, this Plugin is not uploaded to Gradle Plugin Portal, so you have to add the l11n repository to your dependencies.
The gettext installation itself has to be provided by you and will not be delivered with this plugin.
`settings.gradle.kts`
```kotlin
pluginManagement {
repositories {
maven {
url = uri("https://nexus.dev.l11n.de/repository/mvnL11N_RELEASE/")
}
gradlePluginPortal()
}
}
```
`build.gradle.kts`
```kotlin
plugins {
id("de.l11n.gettext.gradle-gettext-plugin") version "+"
}
```
# Configuration
This plugin provides an extension of type `XGettextExtension`, which itself contains some properties and 4 configurations.
The configuration options can mostly be mapped to the options of the corresponding executables.
## `XGettextExtension`
| Setting | DefaultValue | Explanation |
|---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `srcDir` | directory of the project | the root directory to search for matching files with this source configuration |
| `baseOutputDirForPotAndPoFiles` | `localization` | base path for pot and po files on which the corresponding paths will be built |
| `patternPoFilePaths` | `"<LANG>/<DOMAIN_NAME>"` | the pattern used to put po files for translation<br />use the <LANG> placeholder to insert the language<br />use the <DOMAIN_NAME> placeholder to insert the configured defaultDomainName |
| `outputDirCompiledGettextFiles` | `<BUILD_DIR>/gettext/output/` | directory to put compiled files for gettext. This SHOULD be a temporary directory because this files SHOULD not be committed<br />The corresponding files will be in subdirectories sorted by languages e.g.: OUTPUT_DIR/<lang>/messages.mo |
| `translatableLanguages` | `["en_US"]` | list of language codes to generate templates for (e.g. 'en_US', 'de_DE' etc.) |
| `criticalLanguages` | content of `tanslatableLanguages` | which languages should fail if there are missing translations?<br />Default are all translatable languages |
| `xGettextConfig` | default XGettextConfig (see below) | configuration for xgettext tasks |
| `xGettextMsgInitMsgMergeSharedConfig` | default XGettextMsgInitMsgMergeSharedConfig (see below) | shared configuration for xgettext, msginit and msgmerge tasks |
| `msgInitMsgMergeConfig` | default MsgInitMsgMergeConfig (see below) | configuration for msginit and msgmerge tasks |
| `msgFmtConfig` | default MsgFmtConfig (see below) | configuration for msgfmt tasks |
| `verbose` | `false` | increase verbosity level |
| `sourceConfigs` | empty if generateDefaultSourceConfigs is false or java plugin is not applied. Otherwise it contains the configured sources for alle subprojects | if necessary multiple SourceConfigs can be configured<br />by default for each sourceset of the project one sourceConfig will be created. All of them will use the predefined settings of this plugin |
| `taskTimeOutDuration` | `5L` | set the amount of time a task is allowed to run |
| `taskTimeOUtUnit` | `TimeUnit.MINUTES` | set the time unit to measure the run-duration |
| `optionalGettextBinariesPath` | `null` | provide a path to gettext binaries if not installed with git-for-windows on windows or default location on linux |
| `optionalJdkJavaHomePath` | `null` | if you are using jdk >= 17 and gettext <= 0.21 please provide optional path to lower jdk version as gettext sets compile target as 1.6 or 1.7 until version 0.22 |
| `generateDefaultSourceConfigs` | `true` | Let this plugin generate sourceConfigs additional to your specified ones |
## `XGettextConfig`
| Setting | DefaultValue | Explanation |
|-----------------------------|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `defaultDomainName` | `"messages"` | use NAME.po for output (instead of messages.po) |
| `ignoredFiles` | emptyList | files to be ignored by this plugin |
| `fileExtensions` | emptyList | file extensions to filter for. if this is empty all files regardless of their extensions will be analyzed |
| `lang` | `SourceLang.RECOGNIZE` | recognise the specified language (C, C++, ObjectiveC, PO, Shell, Python, Lisp, EmacsLisp, librep, Scheme,<br />Smalltalk, Java, JavaProperties, C#, awk, YCP, Tcl, Perl, PHP, Ruby, GCC-source, NXStringTable, RST, RSJ,<br />Glade, Lua, JavaScript, Vala, Desktop)<br />By default the language is guessed depending on the input file name extension. |
| `fileEncoding` | `StandardCharsets.US_ASCII` | encoding of input files (except for Python, Tcl, Glade) |
| `joinExisting` | `false` | join messages with existing file |
| `commentTag` | `null` | place comment blocks starting with TAG and preceding keyword lines in output file |
| `extractAllComments` | `false` | place all comment blocks preceding keyword lines in output file |
| `checkType` | `CheckType.NONE` | perform syntax check on messages (ellipsis-unicode, space-ellipsis, quote-unicode, bullet-unicode, NONE) |
| `sentenceEndType` | `SentenceEndType.SINGLE_SPACE` | type describing the end of sentence (single-space, which is the default, or double-space) |
| `extractAllStrings` | `false` | extract all strings (only languages C, C++, ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java,<br />C#, awk, Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala) |
| `extraKeyWords` | emptyList | all the extra key words that should be used. From:<br />-kWORD, --keyword=WORD look for WORD as an additional keyword |
| `doNotUseDefaultKeyWords` | `false` | do not to use default keywords (only languages C, C++, ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep,<br />Scheme, Java, C#, awk, Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala, Desktop) |
| `underStandAnsiTrigraphs` | `false` | understand ANSI C trigraphs for input (only languages C, C++, ObjectiveC) |
| `itsTool` | `false` | write out itstool comments |
| `itsFile` | `null` | apply ITS rules from FILE (only XML based languages) |
| `recognizeQt` | `false` | recognize Qt format strings (only language C++) |
| `recognizeKde` | `false` | recognize KDE 4 format strings (only language C++) |
| `recognizeBoost` | `false` | recognize Boost format strings (only language C++) |
| `debug` | `false` | more detailed formatstring recognition result |
| `omitHeader` | `false` | don't write header with 'msgid ""' entry |
| `copyRightHolder` | `"Example Copy Right Holder"` | set copyright holder in output |
| `omitForeignUser` | `false` | omit FSF copyright in output for foreign user |
| `packageName` | `"Default package name"` | set package name in output |
| `packageVersion` | `"0.0.0.0"` | set package version in output |
| `msgIdBugsAddress` | `"support@example.com"` | set report address for msgid bugs |
| `msgStringPrefix` | `null` | use STRING or "" as prefix for msgstr values |
| `msgStringSuffix` | `null` | use STRING or "" as suffix for msgstr values |
| `failIfNoFilesFound` | `true` | fail if no files found. if this is set to false the task will end successful if no files are found |
| `useRelativePathsInComment` | `true` | if this option is enabled, the tasks will filter the project path from file references |
## `XGettextMsgInitMsgMergeSharedConfig`
| Setting | DefaultValue | Explanation |
|---------------------|--------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
| `propertiesOutput` | `false` | write out Java .properties file<br />This configuration is for msgInit and msgMerge jobs |
| `stringTableOutput` | `false` | write out a NeXTstep/GNUstep .strings file<br />This configuration is for msgMerge and msgInit jobs |
| `strict` | `false` | write out strict Uniforum conforming .po file |
| `width` | `0` | set output page width (0 is ignored) |
| `noWrap` | `false` | do not break long message lines, longer than the output page width, into several lines |
| `sorting` | `Sorting.NONE` | sort output. Possible options: SORT, BY_FILE, NONE |
| `forcePo` | `false` | write PO file even if empty |
| `useCEscape` | `use C escapes in output, no extended chars (default false)` | use C escapes in output, no extended chars (default false) |
| `color` | `ColorType.NEVER` | use colors and other text attributes if WHEN. WHEN may be 'always', 'never', 'auto', or 'html'. |
| `colorStyle` | `null` | specify CSS style rule file for --color |
| `indent` | `false` | write the .po file using indented style |
| `addLocation` | `false` | generate '#: filename:line' lines (default) |
## `MsgInitMsgMergeConfig`
| Setting | DefaultValue | Explanation |
|----------------------|--------------|----------------------------------------------------|
| `backupPoFile` | `false` | backup the def.po file used for the msgMerge tasks |
| `backupSuffix` | `null` | override the usual backup suffix |
| `noFuzzyMatching` | `false` | do not use fuzzy matching |
| `keepPreviousMsgIds` | `false` | keep previous msgIds of translated messages |
## `MsgFmtConfig`
| Setting | DefaultValue | Explanation |
|----------------------|-----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `checkFormat` | `false` | check language dependent format strings |
| `checkHeader` | `false` | verify presence and contents of the header entry |
| `checkDomain` | `false` | check for conflicts between domain directives<br />and the --output-file option |
| `checkCompatibility` | `false` | check that GNU msgfmt behaves like X/Open msgfmt |
| `checkAccelerators` | `null` | check presence of keyboard accelerators for menu items<br />This is based on the convention used in some GUIs that a keyboard accelerator in a menu item string is<br />designated by an immediately preceding ‘&’ character. Sometimes a keyboard accelerator is also called<br />"keyboard mnemonic". This check verifies that if the untranslated string has exactly one ‘&’ character,<br />the translated string has exactly one ‘&’ as well. If this option is given with a char argument, this chary<br />should be a non-alphanumeric character and is used as keyboard accelerator mark instead of ‘&’. |
| `noConvert` | `false` | don't convert the messages to UTF-8 encoding |
| `noRedundancy` | `false` | don't pre-expand ISO C 99 <inttypes.h> |
| `alignment` | 1 | align strings to NUMBER bytes (default: 1) |
| `endianness` | `Endianness.PLATFORM_DEFAULT` | write out 32-bit numbers in the given byte order<br />(big or little, default depends on platform) |
| `noHash` | `false` | binary file will not include the hash table |
| `outputModes` | `(project) -> listOf<MsgFmtOutputMode>(BasicOutputFileMode(project))` | provider to configure output modes for msgFmt tasks |
| `msgFmtUseFuzzy` | `false` | use fuzzy entries in output |
## `MsgFmtOutputMode`
There are 9 different output modes for msgFmt as provided in the help text of the executable.
### `BasicOutputFileMode(project: Project)`
This Mode defines simply adds `--output-file=<NAME>.mo` to call parameters. This is the default.
#### `QtMode(project: Project)`
Extends from `BasicOutputFileMode` but changes the output file format to Qt .qm files
#### `DesktopMode(templateFile: File, doNotUseDefaultKeyWords: Boolean, additionalKeyWords: List<String>, project:Project)`
Extends from `BasicOutputFileMode`. Generates a .desktop file.
#### `XmlMode(xmlLanguage: String?, templateFile: File, project:Project)`
Extends from `BasicOutputFileMode`: Generates a .xml file
### `JavaMode(resourceName: String, source: Boolean, subDirectory: String, project: Project)`
Java mode: generate a Java ResourceBundle class. Define if this should be generated as source code or compiled.
#### `Java2Mode(resourceName: String, source: Boolean, subDirectory: String, project: Project)`
Extends from `JavaMode` but assumes Java2 (JDK 1.2 or higher)
### `CSharpMode(resourceName: String, subDirectory: String = "csharp", project: Project)`
Generates a .NET .dll file.
#### `CSharpResourceBundleMode(resource: String, subDirectory: String = "csharp_resources", project: Project)`
Extends from `CSharpMode` but generates a .NET .resources file.
### `TclMode(subDirectory: String, project: Project)`
generate a tcl/msgcat .msg file.
## `SourceConfig`
SourceConfig can be automatically generated or defined by the user. All properties except `project`, `extension` and `srcConfigName` will be extracted from the provided extension. The purpose of these configurations is to provide the ability to create special behaviour for certain sources.
| Setting | DefaultValue | Explanation |
|---------------------------------------|-------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `project` | -- | The project for which this configuration is valid. |
| `extension` | -- | the corresponding extension of the project. |
| `srcConfigName` | -- | name to be used in taskname of this source configuration. |
| `srcDirs` | `listOf(extension.srcDir.get().asFile.toPath())` | the root directory to search for matching files with this source configuration |
| `baseOutputDirForPotAndPoFiles` | `extension.baseOutputDirForPotAndPoFiles.get()` | base path for pot and po files on which the corresponding paths will be built |
| `patternPoFilePaths` | `extension.patternPoFilePaths.get()` | the pattern used to put po files for translation<br />use the <LANG> placeholder to insert the language<br />use the <DOMAIN_NAME> placeholder to insert the configured defaultDomainName |
| `outputDirCompiledGettextFiles` | `extension.outputDirCompiledGettextFiles.get()` | directory to put compiled files for gettext. This SHOULD be a temporary directory because this files SHOULD not be committed<br />The corresponding files will be in subdirectories sorted by languages e.g.: OUTPUT_DIR/<lang>/messages.mo |
| `translatableLanguages` | `extension.translatableLanguages.get()` | list of language codes to generate templates for (e.g. 'en_US', 'de_DE' etc.) |
| `criticalLanguages` | `extension.criticalLanguages.get()` | which languages should fail if there are missing translations?<br />Default are all translatable languages |
| `xGettextConfig` | `extension.xGettextConfig.get()` | configuration for xgettext tasks |
| `xGettextMsgInitMsgMergeSharedConfig` | `extension.xGettextMsgInitMsgMergeSharedConfig.get()` | shared configuration for xgettext, msginit and msgmerge tasks |
| `msgInitMsgMergeConfig` | `extension.msgInitMsgMergeConfig.get()` | configuration for msginit and msgmerge tasks |
| `msgFmtConfig` | `extension.msgFmtConfig.get()` | configuration for msgfmt tasks |
| `verbose` | `extension.verbose.get()` | increase verbosity level |
## Example
Example `build.gradle.kts` configuration with default values:
```kotlin
plugins {
id("de.l11n.gettext.gradle-gettext-plugin") version "+"
}
XGettext {
srcDir.set(project.layout.projectDirectory)
baseOutputDirForPotAndPoFiles.set(project.layout.projectDirectory.dir("localization"))
patternPoFilePaths.set("<LANG>/<DOMAIN_NAME>")
outputDirCompiledGettextFiles.set(project.layout.buildDirectory.dir("gettext/output"))
sourceConfigs.set(emptyList())
translatableLanguages.set(listOf("en_US"))
criticalLanguages.set(translatableLanguages)
verbose.set(false)
xGettextConfig.set(
XGettextConfig {
defaultDomain = "messages"
ignoredFiles = emptyList<File>()
fileExtensions = emptyList<String>()
lang = SourceLang.RECOGNIZE
fileEncoding = StandardCharsets.US_ASCII
joinExisting = false
commentTag = null
extractAllComments = false
checkType = CheckType.NONE
sentenceEndType = SentenceEndType.SINGLE_SPACE
extractAllStrings = false
extraKeyWords = emptyList<String>()
doNotUseDefaultKeyWords = false
underStandAnsiTrigraphs = false
itsTool = false
itsFile = null
recognizeQt = false
recognizeKde = false
recognizeBoost = false
debug = false
omitHeader = false
copyRightHolder = "Example Copy Right Holder"
omitForeignUser = false
packageName = "Default package name"
packageVersion = "0.0.0.0"
msgIdBugsAddress = "support@example.com"
msgStringPrefix = null
msgStringSuffix = null
failIfNoFilesFound = true
useRelativePathsInComment = true
}
)
xGettextMsgInitMsgMergeSharedConfig.set(
XGettextMsgInitMsgMergeSharedConfig {
propertiesOutput = false
stringTableOutput = false
strict = false
width = 0
noWrap = false
sorting = Sorting.NONE
forcePo = false
useCEscape = false
color = ColorType.NEVER
colorStyle = null
indent = false
addLocation = true
}
)
msgInitMsgMergeConfig.set(
MsgInitMsgMergeConfig {
backupPoFile = false
backupSuffix = null
noFuzzyMatching = false
keepPreviousMsgIds = false
}
)
msgFmtConfig.set(
MsgFmtConfig {
checkFormat = false
checkHeader = false
checkDomain = false
checkCompatibility = false
checkAccelerators = null
noConvert = false
noRedundancy = false
alignment = 1
endianness = Endianness.PLATFORM_DEFAULT
noHash = false
msgFmtUseFuzzy = false
outputModes = {
project: Project -> listOf<MsgFmtOutputMode>(BasicOutputFileMode(project))
}
}
)
taskTimeOutDuration.set(5)
taskTimeOutUnit.set(TimeUnit.MINUTES)
generateDefaultSourceConfigs.set(true)
optionalGettextBinariesPath.set(null)
optionalJdkJavaHomePath.set(null)
}
```
Of course every default value can be removed from your configuration, as they are applied automatically. This config is just an example.