Настройка бэкенд локализации
Платформа Citeck поддерживает локализацию сообщений об ошибках на стороне сервера. Исключение и classpath-источник переводов предоставляет ecos-commons, выбор локали — I18nContext, а текст клиентского ответа формируется web-обработчиком.
Формат файла локализации
В микросервисе или библиотеке добавьте JSON-файл в classpath-каталог ecos/messages. Для Maven/Gradle-проекта пример полного пути — src/main/resources/ecos/messages/test-messages.json; в собранном JAR ресурс находится в ecos/messages.
Формат файла:
{
"id": "test-messages",
"locales": [
"en",
"ru"
],
"messages": {
"label.yes": [
"Yes",
"Да"
],
"label.no": [
"No",
"Нет"
],
"server-error-occurred-with-code": [
"Server error occurred. Error code: {{code}}",
"Произошла ошибка на сервере. Код ошибки: {{code}}"
]
}
}
Примечание
Переводы сообщения должны располагаться в том же порядке, что и значения в locales. Для каждого ключа рекомендуется указывать перевод для каждой объявленной локали. Если переводов меньше, отсутствующие значения не заполняются автоматически; лишние значения сверх числа локалей игнорируются.
Ключи сообщений объединяются в общий каталог; id бандла не добавляется к ключу автоматически. Чтобы избежать конфликтов между библиотеками и приложениями, используйте префикс ключа, например ecos-model.type.attribute-id-invalid. На порядок загрузки файлов при совпадении ключей полагаться не следует.
JSON-ресурсы загружаются classpath-источником при первом обращении к каталогу. Ошибки чтения или разбора бандла записываются на уровне WARN, некорректный бандл пропускается. Автоматическое перечитывание файлов после загрузки этим источником не предусмотрено.
В текст можно подставлять параметры в формате:
{{param}}
Использование в коде
Для локализованной ошибки используйте I18nRuntimeException из ecos-commons:
import ru.citeck.ecos.commons.exception.I18nRuntimeException
throw I18nRuntimeException.create()
.messageKey("label.yes")
.build()
Пример с проставлением параметров:
throw I18nRuntimeException.create()
.messageKey("server-error-occurred-with-code")
.messageArgs(
mapOf(
"code" to 500
)
)
.build()
messageKey в builder должен быть непустым. messageArgs заменяет карту параметров; messageArg(name, value) позволяет добавить или заменить один параметр. Причину ошибки можно передать через cause(exception).
Выбор перевода и обработка ошибки
Каталог сначала ищет точное совпадение локали, затем ближайший непустой перевод с тем же языком. Например, для en_US может использоваться en. Перевод другого языка автоматически не выбирается: при наличии только en и ru запрос fr не получает английский перевод из этого каталога.
Если ключ или подходящий перевод отсутствует, classpath-источник возвращает пустую строку. Fallback к ключу сообщения выполняется на уровне I18nContext. Не следует рассчитывать на автоматический английский перевод для клиента с неподдерживаемым языком.
При создании I18nRuntimeException его диагностическое message вычисляется для английской локали с подстановкой параметров. В стандартной web-обработке клиентский текст формируется отдельно, с учётом локали или списка локалей запроса. Конкретное поле ответа зависит от транспорта и обработчика.
Примечание
Английское диагностическое сообщение исключения не гарантирует язык любой записи в логах: обработчик может вывести сообщение внешнего исключения-обёртки или собственный текст.