Formati dei messaggi di localizzazione

Ogni estensione internazionalizzata ha almeno un file denominato messages.json che fornisce stringhe specifiche per le impostazioni internazionali. In questa pagina viene descritto il formato dei file messages.json. Per informazioni su come internazionalizzare e localizzare, consulta la pagina Internazionalizzazione.

Riepilogo campi

Il codice seguente mostra i campi supportati per messages.json. Solo i campi "name" e "message" sono obbligatori.

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."
      },
      ...
    }
  },
  ...
}

Esempio

Ecco un file messages.json che definisce tre messaggi denominati "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"
      }
    }
  }
}

Dettagli campo

Questa sezione descrive tutti i campi che possono essere visualizzati in un file messages.json. Per maggiori dettagli su come viene utilizzato il file dei messaggi, ad esempio cosa succede quando un'impostazione internazionale non definisce tutti i messaggi, vedi Internazionalizzazione.

nome

In realtà non esiste un campo chiamato "nome". Il nome di questo campo è il nome del messaggio, lo stesso nome che vedi in __MSG__name___ o getMessage("_name_").

Il nome è una chiave senza distinzione tra maiuscole e minuscole che consente di recuperare il testo del messaggio localizzato. Il nome può includere i seguenti caratteri:

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

Ecco tre esempi di nomi, tratti dalla sezione Esempio:

messages.json:

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

Per altri esempi sull'utilizzo dei nomi, consulta la pagina Internazionalizzazione.

messaggio

Il messaggio tradotto sotto forma di stringa che può contenere placeholders. Utilizza $_placeholder_name_$ (senza distinzione tra maiuscole e minuscole) per fare riferimento a un segnaposto specifico. Ad esempio, puoi fare riferimento a un segnaposto denominato "nostro_sito" come $our_site$, $OUR_SITE$ o $oUR_sITe$.

Ecco tre esempi di messaggi, tratti dalla sezione Esempio:

messages.json:

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

Per inserire un simbolo del dollaro ($) nella stringa, utilizza $$. For example, use the following code to specify the message Amount (in $):

messages.json:

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


Sebbene i segnaposto come $USER$ siano il metodo preferito per fare riferimento alle stringhe di sostituzione
(stringhe specificate utilizzando il parametro substitutions di i18n.getMessage), puoi anche fare riferimento alle stringhe di sostituzione direttamente all'interno del messaggio. Ad esempio, il seguente messaggio fa riferimento alle prime tre stringhe di sostituzione passate in getMessage():



messages.json:


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



Nonostante questo esempio, ti consigliamo di continuare a utilizzare i segnaposto anziché stringhe $_n_ all'interno dei messaggi. Considera i segnaposto come nomi di variabili utili. Una settimana dopo aver scritto il
codice, probabilmente dimentichi il nome di $1, ma saprai a cosa si riferiscono i segnaposto.
Per ulteriori informazioni sui segnaposto e sulle stringhe di sostituzione, consulta la sezione relativa ai placeholders.



descrizione



Facoltativo. Una descrizione del messaggio, destinata a fornire contesto o dettagli per aiutare il traduttore a effettuare la migliore traduzione possibile.



Ecco tre esempi di descrizioni, tratte dalla sezione Esempio:



messages.json:


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



placeholders



Facoltativo. Definisce una o più sottostringhe da utilizzare all'interno del messaggio. Di seguito sono riportati due motivi per
utilizzare un segnaposto:



    

  • Per definire il testo di una parte del messaggio che non deve essere tradotta. Esempi: codice HTML,
nomi con marchi registrati, identificatori di formattazione.
    • 

  • Per fare riferimento a una stringa di sostituzione passata a getMessage(). Esempio: $1.
    • 




Ogni segnaposto ha un nome, un elemento "contenuti" e un elemento "esempio" facoltativo. Il nome di un segnaposto non fa distinzione tra maiuscole e minuscole e può contenere gli stessi caratteri di un nome di messaggio.



Il valore dell'elemento "content" è una stringa che può fare riferimento a stringhe di sostituzione, specificate mediante il parametro substitutions del metodo i18n.getMessage. Il valore di un elemento "contenuti" è generalmente
ad esempio "Example.com" o "$1". Se fai riferimento a una stringa di sostituzione che
non esiste, ottieni una stringa vuota. La tabella seguente mostra in che modo le stringhe $_n_ corrispondono alle stringhe specificate dal parametro substitutions.



Parametro substitutionsValore di 1 $Valore di 2 $Valore di 3 $
userNamevalore di userName""""
["Cira", "Kathy"]"Cira""Kathy"""



L'elemento "esempio" (facoltativo, ma vivamente consigliato) aiuta i traduttori mostrando come i contenuti
vengono mostrati all'utente finale. Ad esempio, un segnaposto per un importo in dollari deve avere un esempio come "$23.45".



Il seguente snippet, tratto dalla sezione Example, mostra un elemento "placeholder" contenente due segnaposto denominati "our_site" e "user". Il segnaposto "nostro_sito" non contiene elementi "example" perché il suo valore risulta evidente nel campo "content".



messages.json:


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