Um glossário dá ao motor de localização controlo total sobre termos específicos — seja para impor uma tradução exata, seja para impedir por completo a tradução. Os termos do glossário têm prioridade sobre o próprio critério do modelo, por isso o motor aplica-os de forma consistente em todos os pedidos.
Um glossário pertence à organização: é um contentor identificado por nome, onde ficam guardados os termos, e é aplicado a um motor de localização por associação. Um único glossário pode governar todos os motores que precisem dele, e um motor pode aplicar vários.
Como funciona#
| Objeto | Campos |
|---|---|
| Glossário | Nome, descrição e os idiomas de origem que cobre. Pode conter qualquer número de termos. |
| Termo | Idioma de origem, idioma de destino, texto de origem, texto de destino, tipo, dica. |
Quando o motor processa um pedido de tradução, recupera termos relevantes de todos os glossários associados através de pesquisa semântica — fazendo corresponder o significado do texto de entrada aos termos de origem guardados, e não a cadeias 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 elementos não traduzíveis) |
| Tipo | custom_translation ou non_translatable |
| Dica | Contexto opcional para desambiguar o termo (por exemplo, "substantivo, a funcionalidade do produto") |
Os glossários pertencem à organização#
| Ação | Efeito |
|---|---|
| Criar um glossário | Existe ao nível da organização e não se aplica a nada até ser associado |
| Associá-lo a um motor | Todos os seus termos ficam disponíveis para as traduções desse motor |
| Associá-lo a vários motores | Os mesmos termos governam todos eles — edita uma vez, todos os motores seguem |
| Associar vários glossários a um motor | Os respetivos termos juntam-se num único conjunto de recuperação |
| Desassociá-lo de um motor | O motor deixa de o aplicar. O glossário e os seus termos são mantidos. |
| Eliminar um glossário | Recusado enquanto algum motor ainda o aplicar — desassocie-o primeiro. Ao eliminá-lo, os seus termos são eliminados com ele. |
| Eliminar um motor | Os glossários e os termos mantêm-se. Pertencem à organização, não ao motor. |
A ordem de associação não tem qualquer significado. Quando dois glossários associados definem o mesmo texto de origem para o mesmo par de idiomas, qualquer um pode prevalecer — mantenha cada termo num único local.
Gira os glossários em Glossaries na barra lateral da organização. O separador Glossary de um motor lista os termos que está atualmente a aplicar e permite associar ou desassociar glossários.
Idiomas de origem#
Um glossário declara que idiomas de origem cobre. Um custom_translation cujo idioma de origem não seja um deles é recusado na escrita — em todos os fluxos, incluindo o dashboard, a API, uma sugestão do motor aplicada e o provisioning. A verificação usa a mesma correspondência permissiva de idioma que é usada na leitura, por isso um glossário que cobre en aceita um termo em en-US.
Se deixar os idiomas de origem vazios, o glossário aceita qualquer idioma de origem.
Os não traduzíveis estão isentos: não existe uma tradução do idioma de origem à qual fiquem vinculados. Também são armazenados uma única vez com um idioma de destino wildcard, independentemente do destino que enviar — o termo fica protegido em todos os idiomas, por isso cópias por idioma seriam duplicadas.
Tipos de glossário#
Traduções personalizadas#
Force uma tradução específica para um termo. O motor usa sempre 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 estabelecidas
- Adaptações culturais (números de emergência, unidades de medida)
- Termos em que o modelo escolhe sistematicamente o sinónimo errado
Elementos não traduzíveis#
Impeça a tradução de um termo. O motor mantém o texto de origem tal 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 elementos não traduzíveis para:
- Nomes de marcas e de produtos
- Protocolos e normas técnicas
- Nomes próprios que devem permanecer no idioma de origem
Correspondência semântica#
Os termos do glossário são correspondidos pelo significado, não por comparação exata de cadeias. Quando o motor recebe um pedido de tradução, gera embeddings para o texto de entrada e encontra termos cujo texto de origem seja semanticamente semelhante.
Isto significa que um termo para "Deploy" também corresponde a "Deploying", "deployment" e "deploy your application" — sem precisar de entradas separadas para cada variação.
Campo de dica
Use o campo de dica para desambiguar termos com vários significados. Por exemplo, um termo para "bank" com a dica "financial institution" não corresponderá a "river bank" no texto de entrada.
Idiomas universais#
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 alemã específica para este termo em inglês |
Os termos wildcard e os termos específicos por idioma combinam-se — não se sobrepõem entre si.
Correspondência de idiomas#
Os termos do glossário correspondem entre variantes regionais, não apenas entre códigos de idioma exatos. Um termo em de aplica-se a de-DE; um termo em de-DE aplica-se a um pedido simples em de. Variantes paralelas como de-DE e de-AT nunca partilham termos. Quando vários correspondem, prevalece a região predefinida do CLDR. As mesmas regras orientam as vozes da marca, as regras e as configurações do modelo. Consulte Locale Resolution para conhecer 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 cumpre uma função distinta na configuração do motor:
| 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 melhor correspondência |
| Precedência | Mais alta — substitui o julgamento do modelo | Intermédia — orienta o modelo | Mais baixa — define o contexto |
| Exemplo | "Deploy" → "Bereitstellen" | "Abreviar Straße para Str." | "Usar du informal, tom técnico" |
Os três são contentores da organização que um motor aplica por associação: os glossários contêm termos, os rulesets contêm regras e uma voz da marca contém um texto por idioma.
Precedência das regras
Os termos do glossário têm a prioridade mais alta na hierarquia do motor. 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 o duplicar.
Usar glossários com a API#
Os termos do glossário são aplicados automaticamente quando chama o localize endpoint. O motor recupera, dos glossários que aplica, os termos semanticamente relevantes para o par de idiomas de origem e de destino e inclui-os no prompt. Não são necessários parâmetros adicionais.
| Chamada | Finalidade |
|---|---|
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 motores |
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 motor aplica |
DELETE /engines/:id/glossaries/:glossaryId | Deixar de aplicar um glossário a um motor |
GET /engines/:id/glossary-items | Listar todos os termos que um motor aplica atualmente |
ownerEngineId em POST /glossary-items continua a funcionar — escreve no glossário predefinido do motor. Prefira glossaryId.
Acesso#
org:glossary:read e org:glossary:edit controlam os glossários e os termos dentro deles; associar um deles a um motor também requer engine:edit nesse motor. Uma permissão por glossário dá a alguém acesso de leitura e edição a um único glossário, em vez de a todos os glossários da organização. Consulte Roles & Permissions.
Gerir glossários via MCP#
Se utilizar o servidor MCP da Lingo.dev, o seu assistente de programação com IA pode gerir glossários e os respetivos 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."