Formatos das mensagens de localização

Cada extensão ou app internacionalizado tem pelo menos um arquivo chamado messages.json que fornece strings específicas da localidade. Esta página descreve 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. Somente os campos "name" e "message" são obrigatórios.

{
  "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

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

{
  "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 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.

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 incluir os seguintes caracteres:

  • A-Z
  • a-z
  • 0-9
  • _ (sublinhado)
  • @
Observação:não defina nomes que comecem com "@@". Esses nomes são reservados para mensagens predefinidas.

Confira três exemplos de nomes, extraídos da seção Exemplo:

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

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

mensagem

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

Confira três exemplos de mensagens, extraídos da seção Exemplo:

"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 $):

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


Although placeholders such as $USER$ are the preferred way of referring to substitution strings
(strings specified using the substitutions parameter of i18n.getMessage) you can also refer
to substitution strings directly within the message. For example, the following message refers to
the first three substitution strings passed into getMessage():


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



Despite that example, we recommend that you stick to using placeholders instead of $_n_ strings
within your messages. Think of placeholders as good variable names. A week after you write your
code, you'll probably forget what $1 refers to, but you'll know what your placeholders refer to.
For more information on placeholders and substitution strings, see the placeholders section.



description



Optional. A description of the message, intended to give context or details to help the translator
make the best possible translation.



Here are three examples of descriptions, taken from the Example section:


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



placeholders



Optional. Defines one or more substrings to be used within the message. Here are two reasons you
might want to use a placeholder:



    

  • To define the text for a part of your message that shouldn't be translated. Examples: HTML code,
trademarked names, formatting specifiers.
    • 

  • To refer to a substitution string passed into getMessage(). Example: $1.
    • 




Each placeholder has a name, a "content" item, and an optional "example" item. A placeholder's name
is case-insensitive and can contain the same characters as a message name.



The "content" item's value is a string that can refer to substitution strings, which are specified
using the i18n.getMessage method's substitutions parameter. The value of a "content" item is
typically something like "Example.com" or "$1". If you refer to a substitution string that doesn't
exist, you get an empty string. The following table shows how $_n_ strings correspond to strings
specified by the substitutions parameter.



substitutions parameterValue of $1Value of $2Value of $3
userNamevalue of userName""""
["Cira", "Kathy"]"Cira""Kathy"""



The "example" item (optional, but highly recommended) helps translators by showing how the content
appears to the end user. For example, a placeholder for a dollar amount should have an example like
"$23.45".



The following snippet, taken from the Example section, shows a "placeholders" item that
contains two placeholders named "our_site" and "user". The "our_site" placeholder has no "example"
item because its value is obvious from the "content" field.


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