Formate für Lokalisierungsnachrichten

Jede internationalisierte Erweiterung hat mindestens eine Datei mit dem Namen messages.json, die länderspezifische Strings bereitstellt. Auf dieser Seite wird das Format von messages.json-Dateien beschrieben. Informationen zur Internationalisierung und Lokalisierung findest du auf der Seite Internationalisierung.

Felder – Übersicht

Der folgende Code zeigt die unterstützten Felder für messages.json. Nur die Felder "name" und "message" sind erforderlich.

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

Beispiel

In der folgenden messages.json-Datei sind drei Nachrichten mit den Namen „prompt_for_name“, „hello“ und „bye“ definiert:

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

Felddetails

In diesem Abschnitt werden alle Felder beschrieben, die in einer messages.json-Datei enthalten sein können. Weitere Informationen zur Verwendung der Nachrichtendatei – z. B. was passiert, wenn nicht alle Nachrichten in einer Sprache definiert sind –, findest du unter Internationalisierung.

name

Es gibt kein Feld namens „Name“. Der Name dieses Felds ist der Name der Nachricht – derselbe Name, der in __MSG__name___ oder getMessage("_name_") angezeigt wird.

Beim Namen handelt es sich um einen Schlüssel, mit dem Sie den lokalisierten Nachrichtentext abrufen können. Dabei wird die Groß-/Kleinschreibung nicht berücksichtigt. Der Name kann die folgenden Zeichen enthalten:

  • A–Z
  • a-z
  • 0-9
  • _ (Unterstrich)
  • @

Hier sind drei Beispielnamen aus dem Abschnitt Beispiel:

messages.json:

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

Weitere Beispiele zur Verwendung von Namen finden Sie auf der Seite Internationalisierung.

Nachricht

Die übersetzte Nachricht in Form eines Strings, der placeholders enthalten kann. Verwenden Sie $_placeholder_name_$ (keine Unterscheidung zwischen Groß- und Kleinschreibung), um auf einen bestimmten Platzhalter zu verweisen. Beispielsweise können Sie auf einen Platzhalter mit dem Namen „our_site“ $our_site$, $OUR_SITE$ oder $oUR_sITe$ verweisen.

Hier sind drei Beispiele für Nachrichten aus dem Abschnitt Beispiel:

messages.json:

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

Um ein Dollarzeichen ($) in den String einzufügen, verwenden Sie $$. For example, use the following code to specify the message Amount (in $):

messages.json:

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


Platzhalter wie $USER$ sind die bevorzugte Methode, um auf Substitutionsstrings (Strings, die mit dem Parameter Substitutions von i18n.getMessage angegeben werden) zu verweisen. Sie können aber auch direkt in der Nachricht auf Substitutionsstrings verweisen. Die folgende Nachricht bezieht sich beispielsweise auf die ersten drei Ersetzungsstrings, die an getMessage() übergeben werden:



messages.json:


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



Trotz dieses Beispiels empfehlen wir, in Ihren Nachrichten weiterhin Platzhalter anstelle von $_n_-Strings zu verwenden. Platzhalter sind gute Variablennamen. Eine Woche nach dem Schreiben des Codes werden Sie wahrscheinlich vergessen, worauf sich $1 bezieht, aber Sie wissen, worauf sich Ihre Platzhalter beziehen.
Weitere Informationen zu Platzhaltern und Ersetzungsstrings finden Sie im Abschnitt placeholders.



Beschreibung



Optional. Eine Beschreibung der Nachricht, die Kontext oder Details liefert, damit der Übersetzer die bestmögliche Übersetzung erstellen kann.



Hier sind drei Beispielbeschreibungen aus dem Abschnitt Beispiel:



messages.json:


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



placeholders



Optional. Definiert einen oder mehrere Teilstrings, die in der Nachricht verwendet werden sollen. Hier sind zwei Gründe für die Verwendung eines Platzhalters:



    

  • Um den Text für einen Teil Ihrer Nachricht zu definieren, der nicht übersetzt werden soll. Beispiele: HTML-Code, markenrechtlich geschützte Namen, Formatierungsspezifizierer.
    • 

  • Um auf einen Substitutionsstring zu verweisen, der an getMessage() übergeben wird. Beispiel: $1.
    • 




Jeder Platzhalter besteht aus einem Namen, einem Inhaltselement und einem optionalen Beispielelement. Beim Namen eines Platzhalters wird nicht zwischen Groß- und Kleinschreibung unterschieden und er kann die gleichen Zeichen wie ein Nachrichtenname enthalten.



Der Wert des Elements "content" ist ein String, der sich auf Substitutionsstrings beziehen kann, die mit dem Parameter Substitutions der Methode i18n.getMessage festgelegt werden. Der Wert eines Inhaltselements ist in der Regel etwa "Example.com" oder "$1". Wenn Sie auf einen nicht vorhandenen Substitutionsstring verweisen, wird ein leerer String zurückgegeben. Die folgende Tabelle zeigt, wie $_n_-Strings den Strings entsprechen, die durch den Parameter Substitutions angegeben werden.



Substitutions-ParameterWert von 1 $Wert von 2 $Wert von 3 $
userNameWert von userName""""
["Cira", "Kathy"]"Cira""Kathy"""



Das Beispielelement (optional, aber dringend empfohlen) hilft Übersetzern, indem es zeigt, wie der Inhalt für den Endnutzer angezeigt wird. Ein Platzhalter für einen Geldbetrag sollte beispielsweise so aussehen: "$23.45".



Das folgende Snippet aus dem Abschnitt Beispiel zeigt ein „Platzhalter“-Element, das zwei Platzhalter mit den Namen „our_site“ und „user“ enthält. Der Platzhalter „our_site“ enthält kein Beispielelement, da der Wert aus dem Feld „content“ ersichtlich ist.



messages.json:


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