Глоссарий даёт движку локализации точный контроль над конкретными терминами: можно зафиксировать нужный перевод или вовсе запретить переводить термин. Термины глоссария важнее решений модели — движок применяет их одинаково в каждом запросе.
Глоссарий принадлежит организации: это именованный контейнер с терминами, который подключается к движку локализации. Один глоссарий может управлять всеми нужными движками, а движок — использовать сразу несколько глоссариев.
Как это работает#
| Объект | Поля |
|---|---|
| Глоссарий | Название, описание, исходные локали. Содержит любое количество терминов. |
| Термин | Исходная локаль, целевая локаль, исходный текст, целевой текст, тип, подсказка. |
Когда движок обрабатывает запрос на перевод, он извлекает нужные термины из всех подключённых глоссариев с помощью семантического поиска — сопоставляя смысл входного текста с исходными терминами, а не точные строки.
| Поле | Описание |
|---|---|
| Исходная локаль | Локаль исходного текста или * для любого источника |
| Целевая локаль | Локаль целевого текста или * для любой цели |
| Исходный текст | Термин на исходном языке |
| Целевой текст | Обязательный перевод (или тот же термин для непереводимых элементов) |
| Тип | custom_translation или non_translatable |
| Подсказка | Необязательный контекст, который помогает снять неоднозначность термина (например, "существительное, функция продукта") |
Глоссарии принадлежат организации#
| Действие | Результат |
|---|---|
| Создать глоссарий | Появляется на уровне организации, но ни на что не влияет — пока не подключён к движку |
| Подключить к движку | Все термины становятся доступны для переводов этого движка |
| Подключить к нескольким движкам | Одни и те же термины работают везде — изменили один раз, и все движки следуют этому |
| Подключить несколько глоссариев к одному движку | Их термины объединяются в один пул для поиска |
| Отключить от движка | Движок перестаёт применять глоссарий. Сам глоссарий и его термины сохраняются. |
| Удалить глоссарий | Нельзя, пока его использует хотя бы один движок — сначала отключите. При удалении термины удаляются вместе с ним. |
| Удалить движок | Глоссарии и термины остаются. Они принадлежат организации, а не движку. |
Порядок подключения не важен. Если два подключённых глоссария определяют одинаковый исходный текст для одной пары локалей, победить может любой — храните термин в одном месте.
Управляйте глоссариями в разделе Глоссарии на боковой панели организации. Вкладка Глоссарий движка показывает применяемые термины и позволяет подключать или отключать глоссарии.
Исходные локали#
Глоссарий объявляет, какие исходные локали он охватывает. custom_translation, исходная локаль которого не входит в этот список, отклоняется при записи — через любой путь: панель управления, API, предложение движка или провижининг. Проверка использует то же мягкое сопоставление локалей, что и при чтении, — поэтому глоссарий, охватывающий en, принимает термин en-US.
Оставьте исходные локали пустыми — и глоссарий примет любую исходную локаль.
Непереводимые термины — исключение: к ним не привязан исходный перевод. Они хранятся один раз с подстановочной целевой локалью, независимо от того, какую локаль вы указываете, — термин защищён на всех языках, так что отдельные копии для каждой локали были бы дубликатами.
Типы глоссариев#
Пользовательские переводы#
Задайте конкретный перевод для термина. Движок всегда будет использовать его вместо варианта от модели.
| Исходный текст | Целевой текст | Исходная локаль | Целевая локаль |
|---|---|---|---|
| Deploy | Bereitstellen | en | de |
| 911 | 112 | en | de |
| workspace | espace de travail | en | fr |
Используйте пользовательские переводы для:
- Терминологии продукта с устоявшимися переводами
- Культурной адаптации (номера экстренных служб, единицы измерения)
- Терминов, где модель стабильно выбирает не тот синоним
Непереводимые элементы#
Запретите перевод термина. Движок сохраняет исходный текст как есть — для каждой целевой локали.
| Исходный текст | Целевой текст | Тип |
|---|---|---|
| Lingo.dev | Lingo.dev | non_translatable |
| OAuth | OAuth | non_translatable |
| GraphQL | GraphQL | non_translatable |
Используйте непереводимые элементы для:
- Названий брендов и продуктов
- Технических протоколов и стандартов
- Имён собственных, которые должны оставаться на исходном языке
Семантическое сопоставление#
Термины глоссария сопоставляются по смыслу, а не по точному совпадению строк. Когда движок получает запрос на перевод, он строит эмбеддинги для входного текста и находит термины с семантически похожим исходным текстом.
Это значит, что термин для «Deploy» совпадёт и с «Deploying», и с «deployment», и с «deploy your application» — без отдельных записей для каждого варианта.
Поле подсказки
Используйте поле подсказки, чтобы разграничить термины с несколькими значениями. Например, термин «bank» с подсказкой «финансовое учреждение» не совпадёт с «river bank» во входном тексте.
Локали с подстановкой#
Укажите для исходной или целевой локали значение *, чтобы применить термин ко всем парам локалей.
Типовые сценарии:
| Исходный текст | Исходная локаль | Целевая локаль | Сценарий использования |
|---|---|---|---|
| Lingo.dev | * | * | Никогда не переводить название бренда ни на одном языке |
| API | en | * | Оставлять "API" без перевода во всех целевых локалях |
| Deploy | en | de | Использовать конкретный немецкий перевод для этого английского термина |
Подстановочные и локале-специфичные термины дополняют друг друга — они не перекрывают друг друга.
Сопоставление локалей#
Термины глоссария совпадают с региональными вариантами, а не только с точными кодами локалей. Термин de применяется к de-DE; термин de-DE — к запросу с базовой локалью de. Смежные локали, например de-DE и de-AT, термины не делят. Если совпадений несколько, побеждает регион по умолчанию CLDR. Те же правила действуют для тональности бренда, правил и конфигураций моделей. См. Разрешение локалей — там описано полное поведение, включая правило безопасности скриптов для пользовательских переводов.
Глоссарий, правила и тональность бренда#
Каждый из этих элементов решает свою задачу в конфигурации движка:
| Глоссарий | Правило | Тональность бренда | |
|---|---|---|---|
| Управляет | Отдельными терминами | Лингвистические соглашения | Общим тоном и стилем |
| Уровень детализации | Для каждого термина | Для каждого правила | Текст для каждой локали |
| Сопоставление | Семантическое (по смыслу) | Все совпадающие правила применяются | Единственный наиболее подходящий текст |
| Приоритет | Высший — переопределяет решение модели | Средний — направляет модель | Низший — задаёт контекст |
| Пример | "Deploy" → "Bereitstellen" | "Сокращать Straße до Str." | "Использовать неформальное du, технический тон" |
Все три — контейнеры организации, которые движок подключает по необходимости: глоссарии хранят термины, наборы правил — правила, а тональность бренда — один текст на локаль.
Приоритет правил
Термины глоссария имеют наивысший приоритет в иерархии движка. Если термин глоссария конфликтует с правилом — побеждает глоссарий. Создавайте правила так, чтобы они дополняли глоссарий, а не дублировали его.
Использование глоссариев с API#
Термины глоссария применяются автоматически при вызове эндпоинта локализации. Движок извлекает семантически подходящие термины для пары исходная/целевая локаль из подключённых глоссариев и включает их в промпт. Никаких дополнительных параметров не нужно.
| Вызов | Назначение |
|---|---|
POST /glossaries | Создать глоссарий для организации |
GET /organizations/:id/glossaries | Список глоссариев организации с количеством терминов и движков |
GET /glossaries/:id/glossary-items | Список терминов глоссария, сгруппированных по исходному тексту |
POST /glossary-items с glossaryId | Добавить термин в глоссарий |
PUT /engines/:id/glossaries | Заменить набор глоссариев, которые применяет движок |
DELETE /engines/:id/glossaries/:glossaryId | Отключить один глоссарий от движка |
GET /engines/:id/glossary-items | Список всех терминов, которые движок применяет сейчас |
ownerEngineId для POST /glossary-items по-прежнему работает — данные записываются в глоссарий движка по умолчанию. Рекомендуем использовать glossaryId.
Доступ#
org:glossary:read и org:glossary:edit управляют глоссариями и их терминами; чтобы подключить глоссарий к движку, также нужно разрешение engine:edit для этого движка. Разрешение для конкретного глоссария даёт права на чтение и редактирование только этого глоссария — без доступа ко всем остальным в организации. См. Роли и разрешения.
Управление глоссариями через MCP#
Если вы используете Lingo.dev MCP server, ваш AI-ассистент для написания кода может управлять глоссариями и их терминами напрямую:
"Create a glossary called Product terms covering English, and
apply it to the web engine.""Add a term: translate 'workspace' to 'espace de travail'
for English to French.""Mark 'GraphQL' as non-translatable for all locales."