Специфікація¶

Цією бібліотекою можна користуватися, не читаючи цієї сторінки, — підручник і посібник покривають щоденне використання. Ця сторінка — для авторів інструментів: угода, яку реалізує бібліотека, записана як малий, стабільний контракт, щоб інша реалізація — видобувач, IDE, перевірювач типів чи майбутній pygettext — могла на неї орієнтуватися і взаємодіяти. Ті самі правила, пояснені разом із причинами, і те, як їх виконує еталонна реалізація, — спершу читайте Як це працює.

Читати spec v1

Правила на одному екрані¶

msgid — це конкатенація, у вихідному порядку, літеральних сегментів і по одному токену {name} на інтерполяцію. Літеральні дужки екрануються ({ стає {{). Ім'я мусить бути простим іменем заповнювача — str.isidentifier() істинне, і це не ключове слово Python. Перетворення і специфікації формату не є частиною msgid; вони лишаються під контролем застосунку.

t-рядок	msgid
`t"Hello {name}"`	`Hello {name}`
`t"Total: {amount:,.2f}"`	`Total: {amount}`
`t"Config {{raw}} is {value}"`	`Config {{raw}} is {value}`
`t"Hello {user.name}"`	відхилено — не просте ім'я

Переклад припустимий, коли він містить лише голі заповнювачі {name}, кожне обов'язкове ім'я з'являється принаймні раз і не з'являється жодного імені поза дозволеною множиною. Перестановка й повторення свідомо не обмежені: обидва можуть бути граматично необхідними в цільовій мові.

Для множини дозволене — це об'єднання імен гілок, а обов'язкове — їхній перетин: тож t"One file" проти t"{n} files" лишає n доступним перекладачеві будь-якої форми, але обов'язковим у жодній, і правила множини цільової мови можуть відрізнятися від вихідної.

Порожній msgid ніколи не шукається, бо gettext резервує його для метаданих заголовка каталогу.

Відповідність¶

conformance/v1.json — той самий документ у машиночитній формі: випадки, що зіставляють статичну структуру t-рядка з msgid, а msgid плюс шаблон каталогу — з відрендереним рядком або відмовою.

Реалізація відповідає spec v1, коли відтворює кожен випадок. Випадки називають лише те, що визначає специфікація, — виведені msgid, прийняті й відхилені шаблони, відрендерений вивід — і ніколи не називають повідомлення про помилку чи тип винятку, тож реалізація іншою мовою може запускати їх без змін.

Інтерполяції описуються структурно, ніколи як вихідний код Python:

{
  "spec": "2.2",
  "name": "format spec stays out of the msgid",
  "source": [
    "Total: ",
    {"expression": "amount", "value": 1234.5, "format_spec": ",.2f"}
  ],
  "msgid": "Total: {amount}"
}

Поле "spec" — це не версія специфікації: кожен випадок у v1.json належить до spec v1. Воно називає розділ SPEC.md, який цей випадок перевіряє, тож "2.2" читається як §2.2 — правило виведення токена заповнювача.

Еталонна реалізація запускає набір у складі власних тестів, тож проза і код не можуть мовчки розійтися.

Версіонування¶

Це spec v1. Зворотно несумісна зміна виведення msgid або перевірки перекладів збільшує версію і постачає новий conformance/vN.json поруч із наявним. Додаткові уточнення, що не змінюють ні виведених msgid, ні прийнятих шаблонів, — ні.