Localizando mensajes de error

Utilizamos el método req.error() de la API de mensaje tanto en la clase de implementación para AdminService de nuestro escenario como en la clase de implementación para nuestro CatalogService. Utilizamos este método para emitir mensajes de error si fallan las validaciones. Hasta ahora, hemos codificado los mensajes notificados como literales de texto.

En esta lección, aprenderemos a internacionalizar mensajes. En lugar de incrustarlos de codificación fija, se mantienen en archivos separados -llamados paquetes de textos- como pares clave-valor. A continuación, el código de aplicación utiliza las claves para acceder a los textos correspondientes. Esto significa que los valores para las claves son los textos específicos de idioma reales. Para admitir diferentes idiomas, se actualizan diferentes archivos que proporcionan textos traducidos para las mismas claves (véase la siguiente figura). 

El procedimiento detallado es el siguiente: Crear un archivo con el nombre messages.properties en una carpeta llamada _i18n, i18n o asset/i18n. La carpeta del archivo messages.properties debe estar ubicada directamente debajo del directorio del proyecto o en un directorio que contenga archivos que se utilicen para definir modelos de servicio (como el directorio srv de nuestro proyecto).

Los textos necesarios se actualizan como pares clave-valor en el archivo messages.properties. Normalmente, los textos se actualizan allí en inglés. Se pueden utilizar marcadores de posición, que se anotan en la forma "{n} ". n recorre los números naturales empezando por 0.

Para admitir idiomas adicionales, se crean archivos adicionales en la misma carpeta que el archivo messages.properties de acuerdo con la siguiente convención para fijar nombres: messages<_languageCode><_countryCode>.properties. El código de país es opcional. Algunos ejemplos de estos nombres de fichero son messages_de.properties, messages_fr_CA.properties o messages_es_MX.properties.

Los archivos adicionales utilizan las mismas claves que el archivo messages.properties. Sin embargo, los valores de las claves se traducen según el código de idioma y, si procede, el código de país del nombre de archivo.

En el ejemplo que se muestra, se han creado dos archivos .properties: messages.properties con textos en inglés y messages_de.properties con las correspondientes traducciones al alemán.

Supongamos que un texto se consulta mediante una clave al procesar una solicitud, determinándose el alemán para el idioma. Si se actualiza un texto para la clave en el fichero messages_de.properties, la aplicación utilizará este texto. Sin embargo, si no hay ningún archivo messages_de.properties o la clave utilizada no se actualiza en el archivo messages_de.properties existente, CAP vuelve al archivo messages.properties e intenta determinar un valor para la clave mediante este archivo. Si es posible, la aplicación utiliza el texto correspondiente. Si messages.properties tampoco contiene una entrada coincidente, la aplicación utiliza el nombre clave como texto.

Se puede acceder a los textos actualizados en las agrupaciones de textos mediante la API de mensaje, por ejemplo, mediante los métodos req.error() o req.warn(). Para ello, la clave correspondiente simplemente se transfiere a estos métodos en lugar del mensaje real (véase el gráfico siguiente).

Opcionalmente, se puede pasar una matriz con valores de marcador de posición a los métodos desde la API de mensaje como último parámetro. El primer valor de la matriz se utiliza para el marcador de posición {0}, el segundo valor de la matriz para el marcador de posición {1} , etc.

Puede utilizar el parámetro de URL sap-locale para probar diferentes idiomas. En el siguiente ejemplo, se solicitan textos en alemán:

1234567
POST <service_url>/submitOrder?sap-locale=de
Content-Type: application/json

{
  "book": "0ec991dc-95c5-4d8f-91e6-f81a92744781",
  "quantity": 0
}

Como alternativa, también puede utilizar solicitudes con una cabecera Accept-Language adecuada:

12345678
POST <service_url>/submitOrder
Accept-Language: de
Content-Type: application/json

{
  "book": "0ec991dc-95c5-4d8f-91e6-f81a92744781",
  "quantity": 0
}

El parámetro de URL sap-locale tiene la preferencia más alta. Sustituye la cabecera Accept-Language si también se debe fijar.

Vea el vídeo para ver cómo utilizar los mensajes de error localizados.