Реальный payload редко состоит из одного только текста. В том же объекте, где есть title и body, обычно находятся и id, slug, URL ресурса, имя шаблона, enum-код — значения, которые идентифицируют контент или связывают его части между собой, и потому после перевода должны остаться в точности такими же, как на входе. Риск здесь почти незаметен: дайте модели поле с именем id рядом с текстом, который она переводит, и она может решить, что "post-42" лучше смотрится в локализованном виде, нормализовать URL или «исправить» enum. Достаточно одного измененного идентификатора — и в production вы получите битую ссылку или неуспешный lookup, в той локали, где модель решила быть полезной.
lockedKeys избавляет от догадок. Вы указываете ключи, которые не должны меняться, — по точному имени или по glob-шаблону, — и движок локализации исключает эти значения из перевода, а затем дословно возвращает исходные значения в outputData для каждой целевой локали. Заблокированное значение не переводится, не нормализуется и не переписывается. Один и тот же идентификатор на входе — тот же самый идентификатор на выходе в любой локали.
lockedKeys — это поле в запросе create-jobs. Полную структуру запроса и ответ 202 см. в Create jobs; на этой странице разобрано только, что указывать в lockedKeys и как работает сопоставление.
Заблокировать ключ по имени#
Передайте lockedKeys вместе с вашим data. Каждая запись — это шаблон; в самом простом случае это просто имя ключа, которое нужно сохранить.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"data": {
"id": "post-42",
"title": "How async APIs reduce latency",
"tags": ["performance", "infra"],
"author": { "id": "u_abc", "name": "Sam" },
"body": "Async APIs let your app stay responsive while translations process in the background."
},
"lockedKeys": ["id"]
}Простой шаблон id совпадает с ключом id везде, где он встречается как полный сегмент, — здесь это и верхнеуровневый id, и вложенный author.id. В каждом немецком и французском задании outputData сохраняет "post-42" и "u_abc" без изменений. Переводятся только title, name и body; tags остается как есть, потому что в нем нет заблокированного пути, а его строковые значения переводятся как любой другой текст.
Этот последний момент стоит зафиксировать, потому что именно его первым делом спрашивают скептики.
Переводится ли заблокированное значение?
Нет. Ключ, который вы указываете в lockedKeys, исключается из перевода, а его исходное значение дословно возвращается в outputData для каждой целевой локали. Значение, которое вы отправили, вернется без изменений — не переведенным, не нормализованным и не переписанным. Блокировка — это гарантия результата, заданная через lockedKeys, а не подсказка, которую модель должна учесть.
Сопоставление по имени где угодно — или по позиции#
Простой шаблон — это имя ключа, и он совпадает с этим именем как с полным сегментом, на любой глубине и в любом месте дерева. Если audioSrc встречается в двенадцати местах под разными родительскими узлами, один шаблон audioSrc заблокирует все двенадцать. Вам не нужно перечислять пути, чтобы охватить каждое вхождение, — это типичный сценарий, и для него достаточно одной строки.
Если нужен контроль по позиции — заблокировать одно вхождение, но не другое, или каждый элемент массива, но ничего больше, — используйте glob-шаблон, где / служит разделителем пути. Индексы массива выступают как обычные сегменты, поэтому и users/0/email, и users/*/email — допустимые пути.
| Шаблон | Что он блокирует |
|---|---|
audioSrc | Каждый конечный узел audioSrc в дереве, на любой глубине |
metadata | Все поддерево metadata везде, где оно встречается |
metadata/author | Последовательность metadata/author везде, где она встречается, плюс все, что находится ниже |
users/*/email | Email каждого пользователя — * это один сегмент и совпадает с любым индексом |
users/0/email | Только email первого пользователя |
**/{audioSrc,imageSrc} | Оба имени конечных узлов через brace alternation |
Два шаблона выше намеренно блокируют больше, чем один конечный узел. metadata блокирует все поддерево под этим ключом — каждое значение внутри него, независимо от того, выглядит оно переводимым или нет, сохраняется. metadata/author блокирует эту последовательность везде, где она встречается, и все, что находится ниже нее. Блокировку поддерева стоит использовать, когда целый блок носит структурный характер — например, объект конфигурации или сырой embed, — а блокировку конечного узла (metadata/author/name) — когда внутри в остальном переводимого блока нужно сохранить только одно поле.
Glob, а не regex
* совпадает ровно с одним сегментом пути; ** охватывает любое число сегментов; {a,b} — это brace alternation между вариантами. Символьных классов или частичного совпадения токенов здесь нет — шаблоны работают с целыми сегментами пути, а не с подстроками. Пишите users/*/email, а не регулярное выражение.
Что вернется#
Блокировка меняет только то, что переводит модель, — но не форму результата. outputData в точности повторяет структуру входных данных: заблокированные ключи остаются на своих местах со своими исходными значениями, а переводимые строки вокруг них переводятся. Ничего не теряется, не переименовывается и не меняет порядок.
Для входных данных выше outputData каждой локали содержит id: "post-42" и author.id: "u_abc" без изменений, а title, name и body — уже на целевом языке. Полный ответ задания — outputData, поэтапные steps и статус — описан в Get a single job.
Сразу о важном ограничении#
lockedKeys принимает до 100 шаблонов на запрос. Это ограничение на число шаблонов, а не на число ключей, с которыми они совпадают: один audioSrc или users/*/email может заблокировать тысячи значений в большом payload и при этом считается одним шаблоном. Если вы приближаетесь к 100 разным шаблонам, обычно это признак того, что более широкий glob-шаблон (**/{id,slug,href}) или блокировка поддерева выразят ту же идею куда меньшим числом строк.
lockedKeys также действует только для конкретного запроса и носит ad hoc-характер: оно блокирует ключи только для этой группы заданий. Поэтому для терминов, которые не должны переводиться ни в одном задании, — названия продукта, товарного знака функции, единицы измерения, которая должна оставаться буквальной, — надежнее использовать непереводимую запись в glossary вашего движка, которая автоматически применяется при каждом вызове. См. Glossaries. Используйте lockedKeys для структурных полей, завязанных на форму конкретного payload, а glossary — для лексики, которая остается неизменной во всем вашем контенте.
