Formatos das mensagens de localização

Cada extensão internacionalizada tem pelo menos um arquivo chamado messages.json que fornece strings específicas de localidade. Nesta página, descrevemos o formato de arquivos messages.json. Para mais informações sobre como internacionalizar e localizar, consulte a página Internacionalização (em inglês).

Resumo de campos

O código a seguir mostra os campos compatíveis com messages.json. Somente os campos "name" e "message" são obrigatórios.

messages.json:

{
 
"name": {
   
"message": "Message text, with optional placeholders.",
   
"description": "Translator-aimed description of the message.",
   
"placeholders": {
     
"placeholder_name": {
       
"content": "A string to be placed within the message.",
       
"example": "Translator-aimed example of the placeholder string."
     
},
     
...
   
}
 
},
 
...
}

Exemplo

Veja um arquivo messages.json que define três mensagens chamadas "prompt_for_name", "hello" e "bye":

messages.json:

{
 
"prompt_for_name": {
   
"message": "What's your name?",
   
"description": "Ask for the user's name"
 
},
 
"hello": {
   
"message": "Hello, $USER$",
   
"description": "Greet the user",
   
"placeholders": {
     
"user": {
       
"content": "$1",
       
"example": "Cira"
     
}
   
}
 
},
 
"bye": {
   
"message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!",
   
"description": "Say goodbye to the user",
   
"placeholders": {
     
"our_site": {
       
"content": "Example.com",
     
},
     
"user": {
       
"content": "$1",
       
"example": "Cira"
     
}
   
}
 
}
}

Detalhes do campo

Nesta seção, descrevemos cada campo que pode aparecer em um arquivo messages.json. Para detalhes sobre como o arquivo de mensagens é usado, por exemplo, o que acontece quando uma localidade não define todas as mensagens, consulte Internacionalização.

name

Na verdade, não há um campo chamado "name". O nome desse campo é o nome da mensagem, o mesmo nome que você vê em __MSG__name___ ou getMessage("_name_").

O nome é uma chave que não diferencia maiúsculas de minúsculas e permite recuperar o texto localizado da mensagem. O nome pode incluir os seguintes caracteres:

  • A-Z
  • a-z
  • 0-9
  • _ (sublinhado)
  • @

Veja três exemplos de nomes retirados da seção Exemplo:

messages.json:

"prompt_for_name": {
 
...
},
"hello": {
 
...
},
"bye": {
 
...
}

Para mais exemplos do uso de nomes, consulte a página Internacionalização.

mensagem

A mensagem traduzida, na forma de uma string que pode conter placeholders. Use $_placeholder_name_$ (sem diferenciação de maiúsculas e minúsculas) para se referir a um marcador específico. Por exemplo, você pode se referir a um marcador de posição chamado "our_site" como $our_site$, $OUR_SITE$ ou $oUR_sITe$.

Veja três exemplos de mensagens retirados da seção Exemplo:

messages.json:

"message": "What's your name?"
...
"message": "Hello, $USER$"
...
"message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!"

Para colocar um cifrão ($) na string, use $$. For example, use the following code to specify the message Amount (in $):

messages.json:

"message": "Amount (in $$)"

Embora marcadores como $USER$ sejam a maneira preferencial de se referir às strings de substituição (strings especificadas usando o parâmetro substituições de i18n.getMessage), você também pode se referir
às strings de substituição diretamente na mensagem. Por exemplo, a mensagem a seguir se refere
às três primeiras strings de substituição transmitidas para getMessage():



messages.json:



Apesar desse exemplo, recomendamos que você continue usando marcadores em vez de strings $_n_
nas mensagens
. Pense nos espaços reservados como bons nomes de variáveis. Uma semana depois de escrever o
c
ódigo, você provavelmente vai se esquecer a que $1 se refere, mas vai saber a que os marcadores de posição se referem.
Para mais informações sobre marcadores de posição e strings de substituição, consulte a seção de placeholders.



Descrição



Opcional. É uma descrição da mensagem. Ela fornece contexto ou detalhes para ajudar o tradutor a fazer a melhor tradução possível.



Aqui estão três exemplos de descrições extraídas da seção Exemplo:



messages.json:



placeholders



Opcional. Define uma ou mais substrings a serem usadas dentro da mensagem. Veja dois motivos para
usar um marcador de posi
ção:




  • Para definir o texto de uma parte da sua mensagem que não deve ser traduzida. Exemplos: código HTML,
    nomes de marca registrada
    , especificadores de formatação.

  • Para se referir a uma string de substituição transmitida para getMessage(). Exemplo: $1.



Cada marcador de posição tem um nome, um item de "conteúdo" e um item de "exemplo" opcional. O nome de um marcador
n
ão diferencia maiúsculas de minúsculas e pode conter os mesmos caracteres de um nome de mensagem.



O valor do item "content" é uma string que pode se referir a strings de substituição, especificadas com o parâmetro overrides do método i18n.getMessage. O valor de um item "content" normalmente é algo como "Example.com" ou "$1". Se você fizer referência a uma string de substituição que não existe, terá uma string vazia. A tabela a seguir mostra como as strings $_n_ correspondem às strings especificadas pelo parâmetro REPLACEs.



Parâmetro overridesValor de R $1,00Valor de US $2Valor de US $3
userNamevalor de userName""""
["Cira", "Kathy"]"Cira""Kathy"""


O item "exemplo" (opcional, mas altamente recomendado) ajuda os tradutores mostrando como o conteúdo
é exibido para o usuário final. Por exemplo, um marcador de posição para um valor em dólar precisa ter um exemplo como
"$23.45".



O snippet a seguir, retirado da seção Exemplo, mostra um item de "marcadores de posição" que
cont
ém dois marcadores de posição chamados "our_site" e "usuário". O marcador "our_site" não tem o item "example" porque o valor dele é óbvio no campo "content".



messages.json: