Файлы свойств 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:

json
{
  "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 без локали в имени, укажите путь к целевому файлу:

json
{
  "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. Все совпадения внутри каждого значения блокируются. При этом ^ и $ срабатывают на границах строк внутри значения:

json
{
  "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:

sh
lingo push --key checkout.title --wait