Formaty wiadomości dotyczących lokalizacji

Każde spolszczone rozszerzenie lub aplikacja ma co najmniej 1 plik o nazwie messages.json, który zawiera ciągi znaków dla poszczególnych języków. Na tej stronie opisano format plików messages.json. Informacje o międzynarodowej i regionalnej wersji aplikacji znajdziesz na stronie Międzynarodowa wersja aplikacji.

Lista pól

Poniższy kod pokazuje obsługiwane pola w przypadku tagu messages.json. Tylko pole „name” i „wiadomość” – te pola są wymagane.

{
  "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 z 3 wiadomościami o nazwach „prompt_for_name”, „hello” i „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"
      }
    }
  }
}

Szczegóły pola

W tej sekcji opisaliśmy wszystkie pola, które mogą się pojawiać w pliku messages.json. Szczegółowe informacje o używaniu pliku messages, np. o tym, co się dzieje, gdy w przypadku danej wersji językowej nie są zdefiniowane wszystkie komunikaty, znajdziesz w artykule Umiędzynarodowienie.

nazwa

Nie masz żadnego pola o nazwie „name”. Nazwa tego pola to nazwa wiadomości – tak samo nazwa widoczna w __MSG__name___ lub getMessage("_name_").

Nazwa to klucz, w którym wielkość liter nie jest rozróżniana, umożliwiający pobranie zlokalizowanego tekstu wiadomości. Nazwa może zawierają następujące znaki:

  • A–Z
  • a-z
  • 0-9
  • _ (podkreślenie)
  • @
Uwaga: nie twórz nazw zaczynających się od „@@”. Te nazwy są zarezerwowane dla wstępnie zdefiniowanych wiadomości.

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

"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ć zmienne. Użyj $_placeholder_name_$ (wielkość liter nie jest rozróżniana), aby odwołać się do konkretnego obiektu zastępczego. Na przykład obiekt zastępczy o nazwie „nasz_serwis” możesz odwoływać się jako $our_site$, $OUR_SITE$ lub $oUR_sITe$.

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

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

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

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


Chociaż zastępniki takie jak $USER$ są preferowanym sposobem odwoływania się do ciągów zastępczych (ciągów określonych za pomocą parametru substitutions w funkcji i18n.getMessage), możesz też odwoływać się do ciągów zastępczych bezpośrednio w wiadomości. Na przykład ten komunikat odnosi się do
pierwsze trzy ciągi podstawienia przekazywane do funkcji getMessage():


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



Mimo tego zalecamy, aby w wiadomościach używać symboli zastępczych zamiast ciągów znaków $_n_. Puste miejsca to dobre nazwy zmiennych. Tydzień po napisaniu
kodu, prawdopodobnie nie pamiętasz, do czego odnosi się $1, ale będziesz wiedzieć, do czego odnoszą się obiekty zastępcze.
Więcej informacji o zmiennych i ciągach znaków zastępowania znajdziesz w sekcji poświęconej zmiennym.



opis



Opcjonalnie. Opis wiadomości, który ma na celu podanie kontekstu lub szczegółów, aby ułatwić tłumaczowi jak najlepsze przetłumaczenie.



Oto 3 przykłady opisów z sekcji Przykłady:


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



obiekty zastępcze,



Opcjonalnie. Określa co najmniej 1 podciąg, który ma być używany w wiadomości. Oto 2 powody, dla których
możesz użyć zmiennej:



    

  • Aby zdefiniować tekst części wiadomości, która nie powinna być tłumaczona. Przykłady: kod HTML, nazwy zastrzeżonych znaków towarowych, specyfikatory formatowania.
    • 

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




Każdy obiekt zastępczy ma nazwę, element „content” (treść) i opcjonalny element „example” (przykład). Nazwa zastępnika jest nieczuła na wielkość liter i może zawierać te same znaki co nazwa wiadomości.



Treść wartość elementu jest ciągiem znaków, który może odwoływać się do określonych ciągów zastępowania
za pomocą parametru substitutions metody i18n.getMessage. Wartość „treści” element to
zwykle np. „Example.com”; lub „$1”. Jeśli odwołasz się do ciągu zastępczego, którego nie ma, otrzymasz pusty ciąg. W tabeli poniżej pokazano, jak ciągi znaków $_n_ odpowiadają ciągom znaków określonym przez parametr substitutions.



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



Element „Przykład” (opcjonalny, ale bardzo zalecany) pomaga tłumaczom, pokazując, jak treści wyglądają dla użytkownika. Na przykład obiekt zastępczy dla kwoty w dolarach powinien zawierać przykład, taki jak "$23.45".



Ten fragment kodu, pobrany z sekcji Przykład, zawiera element „placeholder” element, który
zawiera dwie obiekty zastępcze o nazwie „our_site” i „user”. Obiekt zastępczy „our_site” nie zawiera elementu „example”, ponieważ jego wartość jest oczywista z pola „content”.


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