Rules
A rule is one named linguistic convention the localization engine applies to a target locale - "abbreviate Straße to Str. in addresses", not "be more casual". Rules live in rulesets: organization-owned containers an engine applies by attachment, so one set of rules can govern every engine that needs it.
Rules were called instructions
The dashboard calls them rules and groups them into rulesets. The REST API still exposes an individual rule at /instructions with its field names unchanged - what changed is where a rule is written: rulesetId replaced ownerEngineId.
How it works#
A ruleset belongs to your organization, not to an engine. Attaching it to an engine is what makes its rules apply - nothing is copied onto the engine.
| Object | Fields |
|---|---|
| Ruleset | Name, description. Holds any number of rules. |
| Rule | Name, target locale (or *), text. |
When a translation request arrives, the engine collects every rule in every attached ruleset whose target locale matches the request's targetLocale and includes them in the LLM prompt alongside the brand voice and glossary. Rules don't compete: all matching rules are included, ordered best-matching-locale first so the tightest guidance leads.
| Field | Description |
|---|---|
| Name | A short label identifying the rule (e.g., "German formal address") |
| Target locale | The locale this rule applies to, or * for all locales (Any locale in the dashboard) |
| Text | The linguistic rule, written in natural language |
Many rules per locale
Create as many rules as a locale needs. Each rule should address one concern - that is what makes it individually testable, scorable by the rules AI review, and safe to delete.
Rulesets are organization-owned#
| Action | Effect |
|---|---|
| Create a ruleset | It exists at organization level and applies to nothing until attached |
| Attach it to an engine | Every rule in it applies to that engine's translations |
| Attach it to several engines | The same rules govern all of them - edit once, every engine follows |
| Attach several rulesets to one engine | All their rules combine |
| Detach it from an engine | The engine stops applying it. The ruleset and its rules are kept. |
| Delete a ruleset | Refused while any engine still applies it - detach first. Deleting takes its rules with it. |
| Delete an engine | Rulesets and rules survive. They belong to the organization, not the engine. |
Manage rulesets under Infrastructure → Rulesets. A ruleset's Rules tab holds its rules; its Settings tab lists the organization's engines, where you apply the ruleset to an engine or stop applying it. From the other side, an engine's Settings tab has a Rulesets section that shows what the engine applies, with Add ruleset to attach another.
Predefined rules#
Lingo.dev curates a catalog of ready-made rules - locale conventions most teams need and few think to write down. They attach to an engine directly rather than through a ruleset, and you can detach them at any time.
The dashboard has no screen for predefined rules. Browse the catalog and attach entries through the API or the MCP server:
| Call | MCP tool | Purpose |
|---|---|---|
GET /predefined-instructions | predefinedInstructions_list | List the catalog |
GET /engines/:id/predefined-instructions | engines_listPredefinedInstructions | List the predefined rules an engine applies |
PUT /engines/:id/predefined-instructions | predefinedInstructions_setForEngine | Replace the set an engine applies - send the full list of ids; anything left out is detached |
DELETE /engines/:id/predefined-instructions/:predefinedInstructionId | predefinedInstructions_detach | Stop applying one entry to an engine |
GET /predefined-instructions/:id/engines?organizationId= | predefinedInstructions_listEngines | List your organization's engines that apply an entry |
Each catalog entry has a target locale, a name, a description, a type (standard, convention, or preference) and a category. Entries that share a groupKey are alternatives for the same locale - an engine can apply at most one of them, and a request that picks two is rejected. Attaching and detaching need engine:edit on the engine; anyone signed in can read the catalog.
Curated rules are placed in the prompt before your own, so a rule you write refines or overrides the baseline instead of fighting it.
Rules vs. brand voices#
Both shape translation output, at different levels:
| Brand Voice | Rule | |
|---|---|---|
| Scope | Overall tone, style, formality | One specific linguistic rule |
| Per locale | One text per locale, one voice per locale per engine | Many rules per locale |
| Applied | The single best-matching text | Every matching rule combines |
| Wildcard | Yes (* acts as the default voice) | Yes (* applies to all locales) |
| Example | "Use informal du, technical tone" | "Always abbreviate Straße to Str. in addresses" |
Use a brand voice to define how your product speaks in a language - formality, register, sentence style.
Use rules to encode specific conventions the model would otherwise miss - abbreviations, punctuation, unit formatting, or locale-specific grammar patterns.
They work together: the brand voice sets the voice, rules handle the edge cases.
Writing effective rules#
Each rule should be a single, unambiguous statement. The engine includes the full text in the LLM prompt, so clarity matters.
Good rules#
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 %.What to avoid#
- Vague guidance that overlaps with the brand voice ("be more casual") - put that in the brand voice instead
- Multiple unrelated conventions in one rule - split them so each can be tested independently
- Rules that contradict the glossary - glossary terms take precedence in the engine's hierarchy
Wildcard locale#
Set the target locale to * (Any locale in the dashboard) to apply a rule across all locales. Useful for language-independent conventions:
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.Locale-specific rules and wildcard rules are both included when the engine processes a request - they combine, not override.
Using rules with the API#
Rules are applied automatically when you call the localize endpoint. The engine collects every rule matching the request's targetLocale (plus any * rules) from the rulesets the engine applies, along with any predefined rules attached to it. No additional parameters are needed.
| Call | Purpose |
|---|---|
POST /rulesets | Create a ruleset for the organization |
GET /organizations/:id/rulesets | List the organization's rulesets with rule and engine counts |
GET /rulesets/:id/rules | List a ruleset's rules |
POST /instructions with rulesetId | Add a rule to a ruleset |
PUT /engines/:id/rulesets | Replace the set of rulesets an engine applies |
DELETE /engines/:id/rulesets/:rulesetId | Stop applying one ruleset to an engine |
GET /engines/:id/instructions | List every rule an engine applies through its rulesets (predefined rules are listed separately) |
ownerEngineId on POST /instructions still works - it writes into the engine's own ruleset, creating one if the engine has none. Prefer rulesetId.
Access#
org:ruleset:read and org:ruleset:edit govern rulesets and the rules inside them; attaching one to an engine also needs engine:edit on that engine. A per-ruleset grant gives someone read and edit on a single ruleset instead of every ruleset in the organization; grants are set through the API or MCP, not the dashboard. See Roles & Permissions.
Managing rules via MCP#
If you use the Lingo.dev MCP server, your AI coding assistant can create, update, and delete rules and rulesets directly:
"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.""List the predefined rules for German and attach the ones
you recommend to the marketing engine."