Настройка бэкенд локализации

Платформа 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-обработке клиентский текст формируется отдельно, с учётом локали или списка локалей запроса. Конкретное поле ответа зависит от транспорта и обработчика.

Примечание

Английское диагностическое сообщение исключения не гарантирует язык любой записи в логах: обработчик может вывести сообщение внешнего исключения-обёртки или собственный текст.