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. Wymagane są tylko pola „name” i „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."
      },
      ...
    }
  },
  ...
}

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 ma pola o nazwie „name”. Nazwa tego pola to nazwa wiadomości – ta sama nazwa, którą widzisz w polu __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 zawierać te znaki:

  • A–Z
  • a-z
  • 0-9
  • _ (podkreślenie)
  • @
Uwaga: nie podawaj 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łumaczoną wiadomość w postaci ciągu tekstowego, który może zawierać miejsca zastępcze; Aby odwołać się do konkretnej zmiennej, użyj $_placeholder_name_$ (wielkość liter nie jest rozróżniana). Na przykład obiekt zastępczy o nazwie „nasz_serwis” możesz wywołać jako $our_site$, $OUR_SITE$ lub $oUR_sITe$.

Oto 3 przykłady wiadomości zaczerpnięte z sekcji Przykład:

"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 $$. 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 komunikat poniżej odnosi się do pierwszych 3 ciągów znaków zastępczych przekazanych do 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 zapomnisz, co oznacza $1, ale będziesz wiedzieć, co oznaczają Twoje zmienne.
Więcej informacji o obiektach zastępczych i ciągu zastępczym znajdziesz w sekcji obiekty zastępcze.



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 przyczyny, dla których warto użyć obiektu zastępczego:



    

  • 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.
    • 

  • Odwołuje się do ciągu zastąpienia przekazanego 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.



Wartość elementu „content” to ciąg znaków, który może odwoływać się do ciągów zastępczych określonych za pomocą parametru substitutions metody i18n.getMessage. Wartość elementu „treść” to zwykle np. „Przykład.com” lub „$1”. Jeśli odwołujesz się do ciągu znaków zastąpienia, który nie istnieje, 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 złWartość 3 PLN
userNamewartość userName""""
["Cira", "Kathy"]"Cira""Kathy"""



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



Poniższy fragment kodu pochodzący z sekcji Przykład przedstawia element „placeholders”, który zawiera 2 zastępcze nazwy o nazwach „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"
  }
}