Java properties
Translate Java .properties resource bundles one key at a time, keeping comments, blank lines and each line's layout.
A .properties file maps keys to messages, one entry per line, as Java's ResourceBundle and Spring's MessageSource read them. The properties file handler translates the value of each key and writes it into a copy of the source file. Comments, blank lines, key order, separators and spacing stay as they were. Only the value of a translated key changes.
Configure properties translation #
A properties file belongs only to a files entry whose pattern ends in .properties, where the format is inferred, or that sets "format": "properties". An entry with "format": "properties" selects only .properties files. A broad pattern such as src/main/resources/**/* without that format never selects a properties file, so configuration files such as application.properties are not translated by accident.
When the file name carries the locale, as in messages_en.properties, each target goes next to it with the target locale in the same place. Locales are written in Java's underscore form, pt_BR, which ResourceBundle looks up:
{
"sourceLocale": "en",
"targetLocales": ["de", "pt-BR"],
"files": [{ "pattern": "src/main/resources/messages_en.properties" }]
}This writes messages_de.properties and messages_pt_BR.properties. A regional source locale is found the same way: with "sourceLocale": "en-US", the source is messages_en_US.properties. Set localeFormat on the entry to write another form, such as "bcp47" for pt-BR. When the source is the default bundle, messages.properties, with no locale in its name, declare the target path:
{
"pattern": "src/main/resources/messages.properties",
"targetPath": "src/main/resources/messages_[locale].properties"
}The same configuration works in the CLI and the GitHub App.
How the file is read #
Keys and values are read the way java.util.Properties reads them:
- Units. Each key is one unit. A key that appears twice is translated once, with the value Java reads, which is the last one. Every occurrence is written with the translation.
- Separators.
=,:or whitespace separates a key from its value, with optional spaces around=and:. - Comments and blank lines. A line whose first non-blank character is
#or!is a comment. Comments and blank lines are never sent for translation. - Continuations. A line ending in
\continues on the next line, whose leading spaces are dropped. A continued value is written back on one line. - Escapes.
\uXXXX,\t,\n,\r,\f,\=,\:,\,\\and any other escaped character are decoded before translation. A malformed\uescape fails the file, as it does in Java. - Empty values. A key whose value is empty or only spaces is kept as it is and not translated. An empty value in a target counts as untranslated, except for a key in
preservedKeys, which keeps it.
The file is read as UTF-8. A file saved in ISO-8859-1 with raw accented bytes is not supported; save it as UTF-8, or write those characters as \uXXXX. A UTF-8 byte order mark at the start of the file is not kept.
How translations are written #
Each translated value is escaped so that Java reads it back unchanged: backslashes, line breaks, tabs, form feeds and other control characters, and a leading space, = or :. Characters past ASCII follow the values already in the file. Comments do not count:
| The values of the target file (or of the source, before the first target exists) | Characters such as é or 中 are written |
|---|---|
| Already hold raw UTF-8 text | As they are |
| Hold only ASCII | As \u00E9, \u4E2D |
When values are escaped, every value written is escaped, including a locked or preserved value that holds raw text in the source. An escaped file loads under both a UTF-8 reader and Properties.load(InputStream), which reads ISO-8859-1.
Placeholders such as {0}, {name} and %s are kept in the translation. Java MessageFormat quoting rules, such as writing '' for an apostrophe in a message with arguments, are not applied for you.
Keep keys and text untranslated #
lockedKeys, preservedKeys and ignoredKeys match the whole key, as the previous CLI did: a pattern matches a key equal to it, a key that continues it after ., / or -, or a key matching it as a glob. So app matches app.title, app.* matches app.title and app.menu.save, and *.port matches server.port. A pattern that starts with $ is a JSONPath query over the keys instead, such as $["app.title"].
| Option | Result in the target |
|---|---|
lockedKeys | The source value, never sent for translation. |
preservedKeys | The target's existing value, or the source value when it has none. |
ignoredKeys | The whole entry is left out, continuation lines included. |
lockedPatterns keeps parts of a value untranslated. Each entry is a regular expression in RE2 syntax, and every match within each value is locked, with ^ and $ matching at line breaks inside a value:
{
"pattern": "src/main/resources/messages_en.properties",
"lockedPatterns": ["\\{\\{[^}]+\\}\\}"]
}A match is sent to the model as a token it must keep, and written back byte for byte. A translation that loses or changes a match is rejected and never written. Patterns match inside each value, not across lines, keys or comments. In a value with a match, placeholders such as {0} and %s are protected the same way.
RE2 runs in time proportional to the text, so it has no lookaround ((?=, (?!, (?<=, (?<!) and no backreferences (\1, \k<name>). Write a character past ASCII as \x{00E9}, not \u00E9. The CLI and the GitHub App refuse a pattern that is not a regular expression when they read the configuration, and the push fails with the pattern named when it uses syntax RE2 does not support. lockedPatterns applies only to properties files: an entry of another format that sets it is refused.
--key narrows a push to the keys it names, with the same matching as lockedKeys.
Reuse and corrections #
A key keeps its existing translation while its source value is unchanged since the last push. When a source value changes, that key is translated again. Keys that exist only in a target file are dropped from it, and target keys follow the source's order and layout.
A push with --key edits the existing target instead: only the selected values change, and the target's other lines, including keys only it has and its comments, stay as they are. A selected key the target lacks is added at its end.
To correct one translation, edit it in the target file. To regenerate it, push it again with --key:
lingo push --key checkout.title --wait