A rule is one named linguistic instruction 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 |
| 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 Rules in the organization sidebar. An engine's Rules tab lists what that engine currently applies and attaches or detaches rulesets.
Predefined instructions#
Lingo.dev curates a catalog of ready-made rules - locale conventions most teams need and few think to write down. Open Predefined Instructions from an engine's Rules tab and pick the ones you want. They attach to the engine directly rather than through a ruleset, and you can detach them at any time.
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 instruction. 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 instructions 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 * 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. 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 currently applies |
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. 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."