Messages API
When interacting with a frontend or mobile application, it is often needed to display localized messages of the application. As those translated values are already defined in the Jmix .messages
files, the Messages API provides the ability to expose those values to the client application.
The Messages API provides the following two endpoints:
-
Entity Translations provides translations for Entities and Entity attributes.
-
Enum Translations provides translations for Enums and its values.
The Messages API by default uses the locale setting of the user obtaining the authorization token and returns the translated values accordingly. |
Entity Translations
The Entity Translations endpoint allows retrieving information about the entity name, and the translated entity attribute names.
/messages/entities
-
Translation for the entity name and attributes of all entities.
/messages/entities/:entityName
-
Translation for the entity name and attributes of the given entity.
In the following example, you can see how to request translated values for the Order
entity through the API:
Order
Entity RequestGET http://localhost:8080/rest
/messages
/entities
/rstex11_Order
{
"rstex11_Order": "Order",
"rstex11_Order.amount": "Amount",
"rstex11_Order.createdBy": "Created by",
"rstex11_Order.createdDate": "Created date",
"rstex11_Order.customer": "Customer",
"rstex11_Order.date": "Date",
"rstex11_Order.deletedBy": "Deleted by",
"rstex11_Order.deletedDate": "Deleted date",
"rstex11_Order.id": "Id",
"rstex11_Order.lastModifiedBy": "Last modified by",
"rstex11_Order.lastModifiedDate": "Last modified date",
"rstex11_Order.lines": "Lines",
"rstex11_Order.version": "Version"
}
Enum Translations
The Enum Translations endpoint allows retrieving information about the enum name, and the translated enum values.
/messages/enums
-
Translation for the enum name and values of all enums.
/messages/enums/:enumClassName
-
Translation for the enum name and values of the given enum.
The parameter enumClassName is the full qualified name of the enum including the package name. So use rest.sample.entity.CustomerType instead of just CustomerType .
|
In the following example, you can see how to request translated values for the CustomerType
enum through the API:
CustomerType
RequestGET http://localhost:8080/rest
/messages
/enums
/rest.sample.entity.CustomerType
{
"rest.sample.entity.CustomerType": "CustomerType",
"rest.sample.entity.CustomerType.BUSINESS": "Business",
"rest.sample.entity.CustomerType.PRIVATE": "Private"
}
Request Specific Languages
It is also possible to explicitly request translated messages for a given locale by setting the Accept-Language
header. In the following example, you can see how to request German translations for the CustomerType
enum:
GET http://localhost:8080/rest
/messages
/enums
/rest.sample.entity.CustomerType
Accept-Language: de
{
"rest.sample.entity.CustomerType": "Kundentyp",
"rest.sample.entity.CustomerType.BUSINESS": "Geschäftskunde",
"rest.sample.entity.CustomerType.PRIVATE": "Privatkunde"
}