Uma regra é uma instrução linguística nomeada que o engine de localização aplica a um idioma de destino — "abrevie Straße para Str. em endereços", não "seja mais casual". As regras vivem em conjuntos de regras: contêineres da organização que um engine aplica ao serem vinculados, para que um único conjunto de regras possa orientar todos os engines que precisarem dele.
As regras antes eram chamadas de instruções
No dashboard, elas aparecem como regras e são agrupadas em conjuntos de regras. A API REST ainda expõe uma regra individual em /instructions, com os nomes dos campos inalterados — o que mudou foi onde a regra é escrita: rulesetId substituiu ownerEngineId.
Como funciona#
Um conjunto de regras pertence à sua organização, não a um engine. É ao vinculá-lo a um engine que suas regras passam a valer — nada é copiado para dentro do engine.
| Objeto | Campos |
|---|---|
| Conjunto de regras | Nome, descrição. Pode conter qualquer quantidade de regras. |
| Regra | Nome, idioma de destino (ou *), texto. |
Quando uma solicitação de tradução chega, o engine reúne todas as regras de todos os conjuntos de regras vinculados cujo idioma de destino corresponda ao targetLocale da solicitação e as inclui no prompt do LLM junto com a voz da marca e o glossário. As regras não competem entre si: todas as regras compatíveis são incluídas, ordenadas com o idioma mais específico primeiro, para que a orientação mais precisa venha na frente.
| Campo | Descrição |
|---|---|
| Nome | Um rótulo curto para identificar a regra (por exemplo, "tratamento formal em alemão") |
| Idioma de destino | O idioma ao qual esta regra se aplica, ou * para todos os idiomas |
| Texto | A regra linguística, escrita em linguagem natural |
Várias regras por idioma
Crie quantas regras um idioma precisar. Cada regra deve tratar de um único ponto — é isso que a torna testável individualmente, avaliável pela avaliação por IA de regras e segura para excluir.
Os conjuntos de regras pertencem à organização#
| Ação | Efeito |
|---|---|
| Criar um conjunto de regras | Ele existe no nível da organização e não se aplica a nada até ser vinculado |
| Vinculá-lo a um engine | Todas as regras nele passam a valer para as traduções desse engine |
| Vinculá-lo a vários engines | As mesmas regras passam a valer para todos eles — edite uma vez e todos os engines seguem |
| Vincular vários conjuntos de regras a um engine | Todas as regras são combinadas |
| Desvinculá-lo de um engine | O engine deixa de aplicá-lo. O conjunto de regras e suas regras são mantidos. |
| Excluir um conjunto de regras | A ação é recusada enquanto algum engine ainda o estiver aplicando — desvincule primeiro. Ao excluir, suas regras também são removidas. |
| Excluir um engine | Os conjuntos de regras e as regras permanecem. Eles pertencem à organização, não ao engine. |
Gerencie os conjuntos de regras em Rules na barra lateral da organização. A aba Rules de um engine mostra o que ele aplica no momento e permite vincular ou desvincular conjuntos de regras.
Instruções predefinidas#
A Lingo.dev mantém um catálogo de regras prontas — convenções de idioma de que a maioria dos times precisa e que poucas pessoas se lembram de documentar. Abra Predefined Instructions na aba Rules de um engine e escolha as que quiser. Elas são vinculadas diretamente ao engine, em vez de passarem por um conjunto de regras, e você pode removê-las a qualquer momento.
As regras selecionadas entram no prompt antes das suas, então uma regra que você escrever refina ou substitui a base, em vez de disputar espaço com ela.
Regras vs. voz da marca#
Ambas moldam o resultado da tradução, mas em níveis diferentes:
| Voz da marca | Regra | |
|---|---|---|
| Escopo | Tom geral, estilo, formalidade | Uma instrução linguística específica |
| Por idioma | Um texto por idioma, uma voz por idioma em cada engine | Várias regras por idioma |
| Aplicação | O único texto com melhor correspondência | Todas as regras compatíveis são combinadas |
| Curinga | Sim (* atua como a voz padrão) | Sim (* se aplica a todos os idiomas) |
| Exemplo | "Use du informal, tom técnico" | "Sempre abrevie Straße para Str. em endereços" |
Use a voz da marca para definir como seu produto se expressa em um idioma — formalidade, registro e estilo das frases.
Use regras para registrar convenções específicas que o modelo poderia deixar passar — abreviações, pontuação, formatação de unidades ou padrões gramaticais específicos de um idioma.
Elas funcionam juntas: a voz da marca define o tom, e as regras cuidam dos casos de exceção.
Como escrever regras eficazes#
Cada regra deve ser uma instrução única e sem ambiguidades. O engine inclui o texto completo no prompt do LLM, então clareza faz toda a diferença.
Boas regras#
Always use the Oxford comma in English lists.In Japanese, use full-width parentheses （）instead of half-width ().For German addresses, abbreviate "Straße" to "Str." and
"Nummer" to "Nr."When translating percentage values for French, add a
non-breaking space before the percent sign: 42 %.O que evitar#
- Orientações vagas que se sobrepõem à voz da marca ("seja mais casual") — coloque isso na voz da marca
- Várias instruções sem relação entre si em uma única regra — separe-as para que cada uma possa ser testada de forma independente
- Regras que contradizem o glossário — os termos do glossário têm precedência na hierarquia do engine
Idioma curinga#
Defina o idioma de destino como * para aplicar uma regra a todos os idiomas. Isso é útil para convenções independentes do idioma:
Never translate product feature names: "Smart Compose",
"Quick Actions", "Flow Builder".Preserve Markdown formatting in all translated strings.
Keep bold (**), italic (*), and link syntax [text](url) intact.Tanto as regras específicas de idioma quanto as regras curinga são incluídas quando o engine processa uma solicitação — elas se combinam, não se substituem.
Usando regras com a API#
As regras são aplicadas automaticamente quando você chama o endpoint localize. O engine reúne todas as regras que correspondem ao targetLocale da solicitação (além de quaisquer regras *) dos conjuntos de regras que ele aplica. Nenhum parâmetro adicional é necessário.
| Chamada | Finalidade |
|---|---|
POST /rulesets | Criar um conjunto de regras para a organização |
GET /organizations/:id/rulesets | Listar os conjuntos de regras da organização com a contagem de regras e engines |
GET /rulesets/:id/rules | Listar as regras de um conjunto de regras |
POST /instructions com rulesetId | Adicionar uma regra a um conjunto de regras |
PUT /engines/:id/rulesets | Substituir o conjunto de conjuntos de regras que um engine aplica |
DELETE /engines/:id/rulesets/:rulesetId | Parar de aplicar um conjunto de regras a um engine |
GET /engines/:id/instructions | Listar todas as regras que um engine aplica no momento |
ownerEngineId em POST /instructions ainda funciona — ele grava no próprio conjunto de regras do engine, criando um se o engine ainda não tiver nenhum. Prefira rulesetId.
Acesso#
org:ruleset:read e org:ruleset:edit controlam os conjuntos de regras e as regras dentro deles; vincular um deles a um engine também exige engine:edit nesse engine. Uma permissão por conjunto de regras dá a alguém acesso de leitura e edição em um único conjunto de regras, em vez de em todos os conjuntos de regras da organização. Veja Roles & Permissions.
Gerenciando regras via MCP#
Se você usa o Lingo.dev MCP server, seu assistente de programação com IA pode criar, atualizar e excluir regras e conjuntos de regras diretamente:
"Create a ruleset called German conventions and apply it to
the marketing engine.""Add a rule to that ruleset: always abbreviate Straße to Str.
in addresses.""Add a wildcard rule: never translate the term Smart Compose."