Localizando mensagens de erro

Usamos o método req.error() do API de mensagem na classe de implementação para o AdminService de nosso cenário e na classe de implementação para nosso CatalogService. Utilizamos este método para emitir mensagens de erro se as validações falharem. Até agora, codificamos as mensagens reportadas como literais de texto.

Nesta lição, aprenderemos a internacionalizar mensagens. Em vez de incorporá-los com programação incondicional, eles são atualizados em arquivos separados - os chamados pacotes de texto - como pares chave-valor. Em seguida, as chaves são utilizadas pelo código de aplicação para acessar os textos correspondentes. Isso significa que os valores para as chaves são os textos reais específicos do idioma. Para suportar idiomas diferentes, são atualizados diferentes arquivos que fornecem textos traduzidos para as mesmas chaves (consulte a figura a seguir). 

O procedimento detalhado é o seguinte: Crie um arquivo com o nome messages.properties em uma pasta chamada _i18n, i18n ou assets/i18n. A pasta para o arquivo messages.properties deve estar localizada diretamente abaixo do diretório do projeto ou em um diretório que contenha arquivos que são usados para definir modelos de serviço (como o diretório srv em nosso projeto).

Os textos necessários são atualizados como pares chave-valor no arquivo messages.properties. Normalmente, os textos são atualizados aí em inglês. Caracteres de preenchimento podem ser usados, que são anotados na forma "{n} ". n percorre os números naturais começando com 0.

Para suportar idiomas adicionais, arquivos adicionais são criados na mesma pasta que o arquivo messages.properties de acordo com a seguinte convenção de nomes: messages<_languageCode><_countryCode>.properties. O código do país é opcional. Exemplos desses nomes de arquivo são messages_de.properties, messages_fr_CA.properties ou messages_es_MX.properties.

Os arquivos adicionais usam as mesmas chaves que o arquivo messages.properties. No entanto, os valores para as chaves são traduzidos de acordo com o código de idioma e, se aplicável, o código do país do nome do arquivo.

No exemplo mostrado, dois arquivos .properties foram criados: messages.properties com textos em inglês e messages_de.properties com as traduções correspondentes em alemão.

Pressuponha que um texto é consultado por meio de uma chave ao processar uma solicitação, em que o alemão foi determinado para o idioma. Se for atualizado um texto para a chave no file messages_de.properties, este texto é utilizado pela aplicação. No entanto, se não houver um arquivo messages_de.properties ou a chave usada não for mantida no arquivo messages_de.properties existente, CAP voltará para o arquivo messages.properties e tentará determinar um valor para a chave por meio desse arquivo. Se isso for possível, o texto correspondente é utilizado pela aplicação. Se messages.properties também não contiver uma entrada correspondente, o aplicativo usará o nome da chave como texto.

Os textos atualizados nos agrupamentos de textos podem ser acessados por meio do API de mensagem, por exemplo, por meio dos métodos req.error() ou req.warn(). Para isso, a chave correspondente é simplesmente transferida para esses métodos em vez da mensagem real (consulte a figura seguinte).

Opcionalmente, uma matriz com valores de espaço reservado pode ser transferida para os métodos da API de mensagem como último parâmetro. O primeiro valor da matriz é depois utilizado para o caractere de preenchimento {0}, o segundo valor da matriz para o caractere de preenchimento {1} e assim por diante.

Você pode usar o parâmetro URL sap-locale para testar diferentes idiomas. No exemplo seguinte, são solicitados textos em alemão:

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

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

Como alternativa, você também pode utilizar solicitações com um cabeçalho Accept-Language apropriado:

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

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

O parâmetro de URL sap-locale tem a preferência mais alta. Ele substitui o cabeçalho Accept-Language caso isso também deva ser definido.

Assista ao vídeo para ver como usar mensagens de erro localizadas.