Файлы свойств Java
Переводите наборы ресурсов Java .properties по одному ключу, сохраняя комментарии, пустые строки и оформление каждой строки.
В файле .properties ключам соответствуют сообщения — по одной записи на строку. Так их читают ResourceBundle в Java и MessageSource в Spring. Обработчик файлов properties переводит значение каждого ключа и записывает его в копию исходного файла. Комментарии, пустые строки, порядок ключей, разделители и пробелы остаются прежними. Меняется только значение переведённого ключа.
Настройка перевода файлов свойств #
Файл свойств обрабатывается только записью files, в которой шаблон заканчивается на .properties или задано "format": "properties". В первом случае формат определяется автоматически. Запись с "format": "properties" выбирает только файлы .properties. Общий шаблон вроде src/main/resources/**/* без указания этого формата никогда не выбирает файлы свойств. Так файлы конфигурации, например application.properties, не попадут на перевод случайно.
Если локаль указана в имени файла, как в messages_en.properties, каждый целевой файл создаётся рядом с исходным, с целевой локалью на том же месте в имени. Локали записываются в принятом в Java формате с подчёркиванием — pt_BR. Именно в таком виде их ищет ResourceBundle:
{
"sourceLocale": "en",
"targetLocales": ["de", "pt-BR"],
"files": [{ "pattern": "src/main/resources/messages_en.properties" }]
}В результате создаются messages_de.properties и messages_pt_BR.properties. Исходный файл с региональной локалью находится так же: при "sourceLocale": "en-US" это будет messages_en_US.properties. Чтобы использовать другой формат записи, задайте localeFormat в записи, например "bcp47" для pt-BR. Если исходный файл — набор ресурсов по умолчанию messages.properties без локали в имени, укажите путь к целевому файлу:
{
"pattern": "src/main/resources/messages.properties",
"targetPath": "src/main/resources/messages_[locale].properties"
}Одна и та же конфигурация работает в CLI и GitHub App.
Чтение файла #
Ключи и значения читаются по тем же правилам, что и в java.util.Properties:
- Единицы перевода. Каждый ключ — отдельная единица перевода. Если ключ встречается дважды, он переводится один раз. Для перевода берётся последнее значение — именно его читает Java. Перевод записывается во все вхождения ключа.
- Разделители. Ключ отделяется от значения символом
=,:или пробельным символом. Вокруг=и:могут быть пробелы. - Комментарии и пустые строки. Если первый непробельный символ строки —
#или!, строка считается комментарием. Комментарии и пустые строки никогда не отправляются на перевод. - Продолжения строк. Если строка заканчивается на
\, она продолжается на следующей строке, а начальные пробелы следующей строки отбрасываются. Значение с продолжением записывается обратно в одну строку. - Экранирование.
\uXXXX,\t,\n,\r,\f,\=,\:,\,\\и любые другие экранированные символы декодируются перед переводом. Некорректная последовательность экранирования\uприводит к ошибке обработки файла, как и в Java. - Пустые значения. Ключ с пустым значением или значением из одних пробелов сохраняется как есть и не переводится. Пустое значение в целевом файле считается непереведённым. Исключение — ключ из
preservedKeys: для него пустое значение сохраняется.
Файл читается в кодировке UTF-8. Файлы в ISO-8859-1 с неэкранированными байтами символов с диакритикой не поддерживаются. Сохраните файл в UTF-8 или запишите эти символы как \uXXXX. Метка порядка байтов UTF-8 в начале файла не сохраняется.
Запись переводов #
Каждое переведённое значение экранируется так, чтобы Java прочитала его без изменений. Экранируются обратные косые черты, переводы строк, символы табуляции, перевода страницы и другие управляющие символы, а также пробел, = или : в начале значения. Символы за пределами ASCII записываются в том же виде, что и в уже имеющихся значениях файла. Комментарии не учитываются:
| Значения целевого файла (или исходного, пока не создан первый целевой файл) | Запись символов вроде é или 中 |
|---|---|
| Уже содержат неэкранированный текст UTF-8 | Как есть |
| Содержат только ASCII | В виде \u00E9, \u4E2D |
Если используется экранирование, оно применяется к каждому записываемому значению. Это касается и заблокированных или сохраняемых значений, которые в исходном файле содержат неэкранированный текст. Экранированный файл можно загрузить как средством чтения UTF-8, так и с помощью Properties.load(InputStream), который читает ISO-8859-1.
Плейсхолдеры вроде {0}, {name} и %s сохраняются в переводе. Правила использования кавычек в Java MessageFormat автоматически не применяются. Например, апостроф в сообщении с аргументами нужно самостоятельно записать как ''.
Сохранение ключей и текста без перевода #
lockedKeys, preservedKeys и ignoredKeys сопоставляются с ключом целиком, как и в прежней версии CLI. Шаблону соответствует ключ, который совпадает с ним, начинается с него и продолжается после ., / или - либо соответствует ему как glob-шаблону. Например, app соответствует app.title, app.* — app.title и app.menu.save, а *.port — server.port. Если шаблон начинается с $, он обрабатывается как JSONPath-запрос по ключам, например $["app.title"].
| Параметр | Результат в целевом файле |
|---|---|
lockedKeys | Исходное значение. Никогда не отправляется на перевод. |
preservedKeys | Текущее значение в целевом файле. Если его нет — исходное значение. |
ignoredKeys | Запись полностью исключается, включая строки продолжения. |
lockedPatterns сохраняет части значения без перевода. Каждая запись — регулярное выражение в синтаксисе RE2. Все совпадения внутри каждого значения блокируются. При этом ^ и $ срабатывают на границах строк внутри значения:
{
"pattern": "src/main/resources/messages_en.properties",
"lockedPatterns": ["\\{\\{[^}]+\\}\\}"]
}Совпадение передаётся модели как токен, который нужно сохранить, и записывается обратно байт в байт. Если перевод теряет или меняет совпадение, он отклоняется и не записывается. Шаблоны ищут совпадения внутри каждого значения, а не между строками, ключами или комментариями. В значении с совпадением плейсхолдеры вроде {0} и %s защищаются так же.
Время работы RE2 пропорционально длине текста, поэтому он не поддерживает проверки вперёд и назад ((?=, (?!, (?<=, (?<!) и обратные ссылки (\1, \k<name>). Записывайте символ за пределами ASCII как \x{00E9}, а не \u00E9. При чтении конфигурации CLI и GitHub App отклоняют шаблон, если он не является регулярным выражением. Если шаблон использует синтаксис, который RE2 не поддерживает, отправка завершается ошибкой с указанием шаблона. lockedPatterns применяется только к файлам свойств: запись другого формата с этим параметром отклоняется.
--key ограничивает отправку указанными ключами. Правила сопоставления те же, что и у lockedKeys.
Повторное использование и исправления #
Существующий перевод ключа сохраняется, если исходное значение не изменилось с последней отправки. Если оно меняется, ключ переводится заново. Ключи, которые есть только в целевом файле, удаляются из него. Порядок ключей и оформление в целевом файле повторяют исходный файл.
При отправке с --key вместо этого редактируется существующий целевой файл. Меняются только выбранные значения. Остальные строки, в том числе ключи, которые есть только в целевом файле, и комментарии остаются как есть. Если выбранного ключа нет в целевом файле, он добавляется в конец.
Чтобы исправить отдельный перевод, отредактируйте его в целевом файле. Чтобы получить новый перевод, повторите отправку с --key:
lingo push --key checkout.title --wait