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

Библиотекой можно пользоваться, не читая эту страницу: повседневное использование описано в учебнике и руководстве. Эта страница — для авторов инструментов: соглашение, реализуемое библиотекой, записано как небольшой стабильный контракт, чтобы другая реализация — экстрактор, IDE, проверка типов или будущий pygettext — могла ориентироваться на него и взаимодействовать. Те же правила с их причинами и то, как их выполняет эталонная реализация, — прочитайте сначала Как это работает.

Читать спецификацию v1

Все правила на одном экране¶

msgid объединяет литеральные сегменты в исходном порядке и токен {name} для каждой интерполяции. Литеральные скобки экранируются ({ становится {{). Имя должно удовлетворять str.isidentifier() и не быть ключевым словом Python. Преобразования и спецификации формата остаются в приложении.

t-string	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 описывает те же правила машиночитаемыми случаями. Реализация соответствует spec v1, если воспроизводит все случаи. Тексты ошибок и типы исключений не входят в критерий.

{
  "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 относится к спецификации v1. Оно называет раздел SPEC.md, который этот случай проверяет, так что "2.2" читается как §2.2 — правило вывода токена заполнителя.

Эталонная реализация запускает этот набор в собственных тестах.

Версионирование¶

Несовместимое изменение генерации msgid или проверки создаёт новую версию и conformance/vN.json. Дополняющее пояснение, не меняющее результатов, версию не меняет.