Ogni app o estensione internazionalizzata ha almeno un file denominato messages.json che fornisce stringhe specifiche per le impostazioni internazionali. Questa pagina descrive il formato dei file messages.json. Per informazioni su come eseguire l'internazionalizzazione e la localizzazione, consulta la pagina Internazionalizzazione.
Riepilogo campi
Il seguente codice mostra i campi supportati per messages.json. Sono obbligatori solo i campi "name" e "message".
{
"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":
{
"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 ogni campo che può essere visualizzato in un file messages.json. Per maggiori dettagli su come viene utilizzato il file dei messaggi, ad esempio cosa succede quando le impostazioni internazionali non definiscono tutti i messaggi, consulta Internazionalizzazione.
nome
In realtà non esiste un campo denominato "name". Il nome di questo campo è il nome del messaggio, lo stesso
nome visualizzato in __MSG__name___ o getMessage("_name_").
Il nome è una chiave senza distinzione tra maiuscole e minuscole che ti 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:
"prompt_for_name": {
...
},
"hello": {
...
},
"bye": {
...
}
Per altri esempi di utilizzo dei nomi, consulta la pagina sull'internazionalizzazione.
messaggio
Il messaggio tradotto, sotto forma di stringa che può contenere segnaposto. Utilizza
$_placeholder_name_$ (non sensibile alle maiuscole) per fare riferimento a un determinato segnaposto. Ad esempio, puoi fare riferimento a un segnaposto denominato "our_site" come $our_site$, $OUR_SITE$ o $oUR_sITe$.
Ecco tre esempi di messaggi, tratti dalla sezione Esempio:
"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 $):
"message": "Amount (in $$)"Anche se i segnaposto come
$USER$sono il modo 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 agetMessage():"message": "Params: $1, $2, $3"Nonostante questo esempio, ti consigliamo di utilizzare sempre i segnaposto anziché le stringhe
$_n_nei tuoi messaggi. Considera i segnaposto come buoni nomi di variabili. Una settimana dopo aver scritto il codice, probabilmente dimenticherai a cosa si riferisce$1, ma saprai a cosa si riferiscono i segnaposto. Per ulteriori informazioni sui segnaposto e sulle stringhe di sostituzione, consulta la sezione relativa ai segnaposto.descrizione
Facoltativo. Una descrizione del messaggio, che ha lo scopo di fornire contesto o dettagli per aiutare il traduttore a eseguire la traduzione migliore possibile.
Ecco tre esempi di descrizioni, tratti dalla sezione Esempio:
"description": "Ask for the user's name" ... "description": "Greet the user" ... "description": "Say goodbye to the user"segnaposto
Facoltativo. Definisce una o più sottostringhe da utilizzare all'interno del messaggio. Ecco due motivi per cui potresti voler utilizzare un segnaposto:
- Per definire il testo di una parte del messaggio che non deve essere tradotta. Esempi: codice HTML, nomi protetti da marchi, specificatori di formattazione.
- 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 messaggio.
Il valore dell'elemento "content" è una stringa che può fare riferimento a stringhe di sostituzione, specificate utilizzando il parametro substitutions del metodo i18n.getMessage. Il valore di un elemento "content" è tipicamente "Example.com" o "1 $". Se fai riferimento a una stringa di sostituzione che non esiste, viene visualizzata una stringa vuota. La seguente tabella mostra come le stringhe $_n_ corrispondono alle stringhe specificate dal parametro substitutions.
| Parametro substitutions | Valore di 1 $ | Valore di 2 $ | Valore di 3 $ |
|---|---|---|---|
userName | valore di userName | "" | "" |
["Cira", "Kathy"] | "Cira" | "Kathy" | "" |
L'elemento "example" (facoltativo, ma vivamente consigliato) aiuta i traduttori mostrando come vengono visualizzati i contenuti per l'utente finale. Ad esempio, un segnaposto per un importo in dollari dovrebbe avere un esempio come
"$23.45".
Lo snippet seguente, tratto dalla sezione Esempio, mostra un elemento "placeholders" che contiene due segnaposto denominati "our_site" e "user". Il segnaposto "our_site" non ha un elemento "example" perché il suo valore è evidente dal campo "content".
"placeholders": {
"our_site": {
"content": "Example.com",
},
"user": {
"content": "$1",
"example": "Cira"
}
}