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 paragetMessage():messages.json:
"message": "Params: $1, $2, $3"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$1se 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:
"description": "Ask for the user's name" ... "description": "Greet the user" ... "description": "Say goodbye to the user"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 overrides | Valor de R $1,00 | Valor de US $2 | Valor de US $3 |
|---|---|---|---|
userName | valor 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:
"placeholders": {
"our_site": {
"content": "Example.com",
},
"user": {
"content": "$1",
"example": "Cira"
}
}