Formaty wiadomości dotyczących lokalizacji

Każde międzynarodowe rozszerzenie ma co najmniej 1 plik o nazwie messages.json zawierający ciągi znaków specyficzne dla języka. Na tej stronie opisaliśmy format plików messages.json. Informacje o umiędzynarodowieniu i lokalizacji znajdziesz na stronie Internacjonalizacja.

Lista pól

Poniższy kod przedstawia obsługiwane pola w przypadku messages.json. Wymagane są tylko pola „name” i „message”.

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

Przykład

Oto plik messages.json, który definiuje 3 komunikaty o nazwach „prompt_for_name”, „hello” i „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"
      }
    }
  }
}

Szczegóły pola

W tej sekcji opisujemy wszystkie pola, które mogą się pojawić w pliku messages.json. Szczegółowe informacje o sposobie używania pliku wiadomości – na przykład o tym, co się dzieje, gdy język nie definiuje wszystkich wiadomości – znajdziesz w artykule Internacjonalizacja.

nazwa

Nie masz pola o nazwie „name”. Nazwa tego pola jest nazwą wiadomości – jest to ta sama nazwa, która jest widoczna w __MSG__name___ lub getMessage("_name_").

Nazwa jest kluczem bez rozróżniania wielkości liter, który umożliwia pobranie zlokalizowanego tekstu wiadomości. Nazwa może zawierać te znaki:

  • A–Z
  • a-z
  • 0-9
  • _ (podkreślenie)
  • @

Oto 3 przykłady nazw zaczerpnięte z sekcji Przykład:

messages.json:

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

Więcej przykładów użycia nazw znajdziesz na stronie Internacjonalizacja.

wiadomość

Przetłumaczona wiadomość w formie ciągu znaków, który może zawierać placeholders. Aby odwołać się do określonej zmiennej, użyj $_placeholder_name_$ (wielkość liter nie jest rozróżniana). Na przykład obiekt zastępczy o nazwie „our_site” może mieć postać $our_site$, $OUR_SITE$ lub $oUR_sITe$.

Oto 3 przykłady wiadomości pobrane z sekcji Przykład:

messages.json:

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

Aby umieścić w ciągu znaków znak dolara ($), użyj funkcji $$. For example, use the following code to specify the message Amount (in $):

messages.json:

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


Zmienne takie jak $USER$ są preferowanym sposobem odwoływania się do ciągów do podstawienia (ciągów do podstawienia określonych za pomocą parametru substitutions parametru i18n.getMessage), ale możesz też odwoływać się do ciągów do podstawienia bezpośrednio w wiadomości. Na przykład ten komunikat odnosi się do pierwszych 3 ciągów podstawienia przekazanych do getMessage():



messages.json:


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



Mimo to zalecamy stosowanie w wiadomościach obiektów zastępczych zamiast ciągów znaków $_n_. Symbole zastępcze to dobre nazwy zmiennych. Tydzień po napisaniu kodu prawdopodobnie zapomnisz, do czego odnosi się $1, ale będziesz wiedzieć, do czego odwołują się symbole zastępcze.
Więcej informacji o obiektach zastępczych i ciągach zastępczych znajdziesz w sekcji na temat placeholders.



opis



Opcjonalne. Opis wiadomości mający zapewnić kontekst lub szczegółowe informacje, które pomogą tłumaczowi w dopracowaniu możliwego przekładu.



Oto 3 przykłady opisów wziętych z sekcji Przykład:



messages.json:


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



placeholders



Opcjonalne. Definiuje co najmniej jeden podłańcuch, który ma być używany w wiadomości. Oto 2 powody, dla których warto
użyć symbolu zastępczego:



    

  • Umożliwia zdefiniowanie tekstu części wiadomości, która nie powinna być tłumaczona. Przykłady: kod HTML, nazwy znaków towarowych, specyfikacje formatowania.
    • 

  • Aby odwołać się do ciągu podstawienia przekazanego do getMessage(). Przykład: $1.
    • 




Każdy symbol zastępczy ma nazwę, element „treść” i opcjonalny element „przykład”. W nazwie obiektu zastępczego wielkość liter nie jest rozróżniana i może zawierać te same znaki co nazwa wiadomości.



Wartość elementu „content” jest ciągiem znaków, który może się odwoływać do ciągów do podstawienia, które są określane za pomocą parametru substitutions metody i18n.getMessage. Wartość elementu „content” to zwykle „Example.com” lub „$1”. Jeśli odwołujesz się do ciągu zastąpienia, który nie istnieje, otrzymasz pusty ciąg znaków. W tabeli poniżej pokazujemy, jak ciągi $_n_ odpowiadają ciągom określonym przez parametr substitutions.



Parametr substitutionsWartość 1 USDWartość 2 złWartość 3 zł
userNamewartość userName""""
["Cira", "Kathy"]"Cira""Kathy"""



Element „example” (opcjonalny, ale zdecydowanie zalecany) pomaga tłumaczom, pokazując, jak treść jest prezentowana użytkownikowi. Na przykład symbol zastępczy kwoty pieniężnej powinien mieć postać "$23.45".



Poniższy fragment, pochodzący z sekcji Przykład, zawiera element „zmienny”, który zawiera 2 obiekty zastępcze o nazwach „our_site” i „user”. Symbol zastępczy „our_site” nie zawiera elementu „example”, ponieważ jego wartość jest oczywista w polu „content”.



messages.json:


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