Formatos das mensagens de localização

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

Resumo de campos

O código a seguir mostra os campos compatíveis com messages.json. Apenas 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

Este é um arquivo messages.json que define três mensagens chamadas "prompt_for_name", "hello" e "tchau":

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

Esta seção descreve cada campo que pode aparecer em um arquivo messages.json. Para mais detalhes sobre como o é usado. Por exemplo, o que acontece quando uma localidade não define todas as mensagens. Consulte Internacionalização.

nome

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

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

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

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

messages.json:

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

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

mensagem

A mensagem traduzida, na forma de uma string que pode conter marcadores de posição. Usar $_placeholder_name_$ (não diferencia maiúsculas de 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$.

Confira 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 os marcadores de posição, como $USER$, sejam a maneira preferida de se referir a strings de substituição,
strings especificadas usando o parâmetro substitutions de i18n.getMessage, também é possível se referir
a strings de substituição diretamente na mensagem. Por exemplo, a mensagem a seguir se refere
as três primeiras strings de substituição transmitidas para getMessage():



messages.json:


"message": "Params: $1, $2, $3"



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



descrição



Opcional. Uma descrição da mensagem, com o objetivo de fornecer contexto ou detalhes para ajudar o tradutor
a fazer a melhor tradução possível.



Confira três exemplos de descrições, retirados da seção Exemplo:



messages.json:


"description": "Ask for the user's name"
...
"description": "Greet the user"
...
"description": "Say goodbye to the user"



marcadores de posição



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



    

  • Para definir o texto de uma parte da mensagem que não será traduzida. Exemplos: código HTML,
nomes de marcas registradas e especificadores de formatação.
    • 

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




Cada marcador tem um nome, um "conteúdo" item de linha e um "exemplo" opcional do item de linha. 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, que são especificadas
usando o parâmetro substitutions do método i18n.getMessage. O valor de um "conteúdo" o item é
normalmente, algo como "Example.com" ou "$1". Se você se referir a uma string de substituição que não
existir, você receberá uma string vazia. A tabela a seguir mostra como as strings $_n_ correspondem às strings
especificado pelo parâmetro overrides.



parâmetro REPLACEsValor de US$ 1Valor 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
aparece para o usuário final. Por exemplo, um marcador de posição para um valor em dólares precisa ter um exemplo como
"$23.45".



O snippet a seguir, retirado da seção Exemplo, mostra um "marcador de posição" item que
contém dois marcadores de posição chamados "our_site" e "usuário". O "nosso_site" o marcador de posição não tem "exemplo"
item, porque seu valor é óbvio no "conteúdo" .



messages.json:


"placeholders": {
  "our_site": {
    "content": "Example.com",
  },
  "user": {
    "content": "$1",
    "example": "Cira"
  }
}