Um glossário dá ao engine de localização controle preciso sobre termos específicos — seja para impor uma tradução exata ou impedir totalmente a tradução. Os termos do glossário têm prioridade sobre o próprio julgamento do modelo, então o engine os aplica de forma consistente em todas as solicitações.
Um glossário pertence à organização: é um contêiner nomeado que armazena termos e é aplicado a um engine de localização por meio de vínculo. Um único glossário pode governar todos os engines que precisarem dele, e um engine pode aplicar vários.
Como funciona#
| Objeto | Campos |
|---|---|
| Glossário | Nome, descrição e os idiomas de origem que ele cobre. Pode conter qualquer quantidade de termos. |
| Termo | Idioma de origem, idioma de destino, texto de origem, texto de destino, tipo, dica. |
Quando o engine processa uma solicitação de tradução, ele recupera termos relevantes de todos os glossários vinculados usando busca semântica — relacionando o significado do texto de entrada aos termos de origem armazenados, e não a strings exatas.
| Campo | Descrição |
|---|---|
| Idioma de origem | O idioma do texto de origem, ou * para qualquer origem |
| Idioma de destino | O idioma do texto de destino, ou * para qualquer destino |
| Texto de origem | O termo no idioma de origem |
| Texto de destino | A tradução obrigatória (ou o mesmo termo, no caso de itens não traduzíveis) |
| Tipo | custom_translation ou non_translatable |
| Dica | Contexto opcional para desambiguar o termo (por exemplo, "substantivo, funcionalidade do produto") |
Glossários pertencem à organização#
| Ação | Efeito |
|---|---|
| Criar um glossário | Ele existe no nível da organização e não se aplica a nada até ser vinculado |
| Vinculá-lo a um engine | Todos os termos nele ficam disponíveis para as traduções desse engine |
| Vinculá-lo a vários engines | Os mesmos termos governam todos eles — edite uma vez, e todos os engines acompanham |
| Vincular vários glossários a um engine | Seus termos se combinam em um único conjunto de recuperação |
| Desvinculá-lo de um engine | O engine deixa de aplicá-lo. O glossário e seus termos são mantidos. |
| Excluir um glossário | A ação é recusada enquanto algum engine ainda o aplicar — desvincule primeiro. Ao excluir, seus termos vão junto. |
| Excluir um engine | Glossários e termos permanecem. Eles pertencem à organização, não ao engine. |
A ordem de vinculação não tem significado. Quando dois glossários vinculados definem o mesmo texto de origem para o mesmo par de idiomas, qualquer um deles pode prevalecer — mantenha cada termo em um só lugar.
Gerencie glossários em Glossaries na barra lateral da organização. A aba Glossary de um engine lista os termos que ele aplica no momento e permite vincular ou desvincular glossários.
Idiomas de origem#
Um glossário declara quais idiomas de origem ele cobre. Um custom_translation cujo idioma de origem não seja um deles é recusado na gravação — em todos os caminhos, incluindo o dashboard, a API, uma sugestão de engine aplicada e o provisioning. A verificação usa a mesma correspondência permissiva de idioma do momento da leitura, então um glossário que cobre en aceita um termo en-US.
Deixe os idiomas de origem vazios e o glossário aceitará qualquer idioma de origem.
Itens não traduzíveis são exceção: não existe tradução no idioma de origem à qual vinculá-los. Eles também são armazenados uma única vez com um idioma de destino curinga, independentemente do destino enviado — o termo fica protegido em todos os idiomas, então cópias por idioma seriam duplicadas.
Tipos de glossário#
Traduções personalizadas#
Force uma tradução específica para um termo. O engine sempre usa a sua tradução em vez da do modelo.
| Texto de origem | Texto de destino | Idioma de origem | Idioma de destino |
|---|---|---|---|
| Deploy | Bereitstellen | en | de |
| 911 | 112 | en | de |
| workspace | espace de travail | en | fr |
Use traduções personalizadas para:
- Terminologia de produto com traduções já estabelecidas
- Adaptações culturais (números de emergência, unidades de medida)
- Termos para os quais o modelo escolhe com frequência o sinônimo errado
Itens não traduzíveis#
Impeça que um termo seja traduzido. O engine mantém o texto de origem como está, em qualquer idioma de destino.
| Texto de origem | Texto de destino | Tipo |
|---|---|---|
| Lingo.dev | Lingo.dev | non_translatable |
| OAuth | OAuth | non_translatable |
| GraphQL | GraphQL | non_translatable |
Use itens não traduzíveis para:
- Nomes de marcas e produtos
- Protocolos e padrões técnicos
- Nomes próprios que devem permanecer no idioma de origem
Correspondência semântica#
Os termos do glossário são associados por significado, não por comparação exata de strings. Quando o engine recebe uma solicitação de tradução, ele gera embeddings para o texto de entrada e encontra termos com texto de origem semanticamente semelhante.
Isso significa que um termo para "Deploy" também corresponde a "Deploying", "deployment" e "deploy your application" — sem precisar de entradas separadas para cada variante.
Campo de dica
Use o campo de dica para desambiguar termos com múltiplos significados. Por exemplo, um termo para "bank" com a dica "financial institution" não corresponderá a "river bank" no texto de entrada.
Idiomas curinga#
Defina o idioma de origem ou de destino como * para aplicar um termo a todos os pares de idiomas.
Padrões comuns:
| Texto de origem | Idioma de origem | Idioma de destino | Caso de uso |
|---|---|---|---|
| Lingo.dev | * | * | Nunca traduzir o nome da marca em nenhum idioma |
| API | en | * | Manter "API" sem tradução em todos os idiomas de destino |
| Deploy | en | de | Usar a tradução específica em alemão para este termo em inglês |
Termos curinga e termos específicos por idioma se combinam — eles não substituem uns aos outros.
Correspondência de idioma#
Os termos do glossário correspondem entre variantes regionais, não apenas entre códigos exatos de idioma. Um termo de se aplica a de-DE; um termo de-DE se aplica a uma solicitação genérica de. Variantes irmãs, como de-DE e de-AT, nunca compartilham termos. Quando várias correspondências existirem, a região padrão do CLDR prevalece. As mesmas regras orientam vozes da marca, regras e configurações de modelo. Consulte Locale Resolution para ver o comportamento completo, incluindo a regra de segurança de script para traduções personalizadas.
Glossário vs. regras vs. voz da marca#
Cada um tem um papel distinto na configuração do engine:
| Glossário | Regra | Voz da marca | |
|---|---|---|---|
| Controla | Termos individuais | Convenções linguísticas | Tom e estilo gerais |
| Granularidade | Por termo | Por regra | Texto por idioma |
| Correspondência | Semântica (por significado) | Todas as regras correspondentes incluídas | O único texto com a melhor correspondência |
| Precedência | Mais alta — sobrepõe o julgamento do modelo | Média — orienta o modelo | Mais baixa — define o contexto |
| Exemplo | "Deploy" → "Bereitstellen" | "Abreviar Straße para Str." | "Use du informal, tom técnico" |
Os três são contêineres pertencentes à organização que um engine aplica por vínculo: glossários armazenam termos, rulesets armazenam regras, e uma voz da marca armazena um texto por idioma.
Precedência das regras
Os termos do glossário têm a maior prioridade na hierarquia do engine. Se um termo do glossário entrar em conflito com uma regra, o glossário prevalece. Crie regras para complementar o glossário, não para duplicá-lo.
Usando glossários com a API#
Os termos do glossário são aplicados automaticamente quando você chama o localize endpoint. O engine recupera, dos glossários que aplica, os termos semanticamente relevantes para o par de idioma de origem e destino e os inclui no prompt. Nenhum parâmetro adicional é necessário.
| Chamada | Objetivo |
|---|---|
POST /glossaries | Criar um glossário para a organização |
GET /organizations/:id/glossaries | Listar os glossários da organização com contagens de termos e de engines |
GET /glossaries/:id/glossary-items | Listar os termos de um glossário, agrupados por texto de origem |
POST /glossary-items com glossaryId | Adicionar um termo a um glossário |
PUT /engines/:id/glossaries | Substituir o conjunto de glossários que um engine aplica |
DELETE /engines/:id/glossaries/:glossaryId | Parar de aplicar um glossário a um engine |
GET /engines/:id/glossary-items | Listar todos os termos que um engine aplica no momento |
ownerEngineId em POST /glossary-items ainda funciona — grava no glossário padrão do engine. Prefira glossaryId.
Acesso#
org:glossary:read e org:glossary:edit governam os glossários e os termos dentro deles; vinculá-lo a um engine também exige engine:edit nesse engine. Uma permissão por glossário dá a alguém acesso de leitura e edição em um único glossário, em vez de em todos os glossários da organização. Consulte Roles & Permissions.
Gerenciando glossários via MCP#
Se você usa o servidor MCP do Lingo.dev, seu assistente de programação com IA pode gerenciar glossários e seus termos diretamente:
"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."