Patois.

Docs · Features

Engines and providers

Engines are the models that do the work, your local server, a cloud LLM, or a machine-translation service, and every step, judge and extraction resolves one.

What it does#

Nothing in Localization OS translates anything by itself, it orchestrates models. This is where you tell it which model to use, and how to reach it. A built-in provider slot goes live the moment its key, or for a local server its base URL, is configured. You can also create a named, fully configured engine profile with its own base URL, key, model and settings, referenced by any workflow step that wants it.

Three states matter. Mock: no key or base URL configured, everything runs but nothing is real, useful for trying the product with no setup at all. Local: your own model server, no per-call cost, works offline. Cloud: a configured provider, with real spend tracked per call and optionally capped with a monthly ceiling.

Parallel jobs per engine. A local engine can carry its own Max parallel jobs limit, so a model server with several slots runs that many translate jobs at once while other engines keep their own pace. It works below the install's global job-worker count, and a job over the limit waits in the queue without holding a worker.

Local models warm up when a run starts. A llama.cpp server in router mode is asked to preload the models a workflow's steps use, so a later step does not wait for its model to load. It is best effort, in the background, and never delays or changes the run.

Outages fail clearly. A local engine that restarts mid-run is retried on a longer ladder, about 78 seconds in total, when no failover engine is set. A cut stream counts as a failed attempt, never as a complete translation. If the engine does not come back, the segment fails with the engine's error and the run ends failed; later calls fail fast for a minute instead of each waiting out the ladder.

Getting started#

  1. Start your local model server and load a model.
  2. In the web UI, go to Setup AI, Local / self-hosted engine, and set the base URL.
  3. Use Test connection, then Fetch models, and pick one as the default.
  4. Leave workflow steps' provider as local with a blank model, so they all use that default, and changing it later changes them all at once.
config set local_base_url http://localhost:1234/v1
providers key set claude
engine create --name "DeepL prod" --kind deepl --secret api_key=YOUR_KEY
engine list

Quality judges#

Most engines translate. A quality judge never does: it reads a source segment and its translation, answers a fixed set of questions about the pair, and Localization OS turns the answers into a score and a pass, fail or undecided verdict for a workflow step's QE gate. Setup AI lists judges in their own group, Quality judges, below the translation engines, and a judge appears only in a step's QE judge engine picker. Every translation picker hides it.

There are two kinds, both speaking the Jev System One protocol:

  • Jev (TypeSafe, hosted): paste your TypeSafe API key. The address is fixed to TypeSafe's API, so the key is never sent anywhere else. Every call is priced, tracked in spend, and checked against the monthly spend cap before it is sent; once the cap is reached, no call goes out.
  • Jev-compatible local server (SemIf, Kev): any server that speaks the same protocol, such as SemIf running on your own GPU, on the same machine as Localization OS or over Tailscale. Give it the server's Base URL; the API key is optional, but set one whenever the server is reachable over the network. Calls cost nothing and never count against the spend cap. The Quality judges page walks through running SemIf and connecting it.

To add one, open Setup AI, then + Add engine under Engines, pick one of the two kinds, and press Add engine. On the new card, open Edit and press Test: it lists the server's models, says whether the configured model is among them, and asks one small question. Then open the workflow, edit a Translate step, and pick the judge as its QE judge engine. If the install already has a TYPESAFE_API_KEY environment variable, an administrator can turn it into a hosted Jev engine with one button, Create a Jev engine from TYPESAFE_API_KEY; the key is stored encrypted and never shown.

Every judge card also has an Inspect button for administrators. The Inspect page shows the questions the judge is asked and the exact request body, the decision rule rendered from the same numbers the gate uses, a Try it form that scores one segment and shows the request, the raw answer, the verdict and the exact prompt the auto-fix post-editor would receive, and a link to the LLM Ledger filtered to that engine.

engine create --name "Jev" --kind jev --secret api_key=YOUR_TYPESAFE_KEY
engine create --name "SemIf" --kind jev_local --base-url http://127.0.0.1:8077
engine test 7
engine inspect 7

Works with#

  • Workflows: every translate and check step resolves an engine, its own provider and model if set, otherwise the run default. A Translate step's QE gate can use a quality judge, and its opt-in auto-fix uses an LLM engine as the post-editor.
  • Quality judges: hosted Jev, or a Jev-compatible server such as SemIf that you run yourself, locally or over Tailscale.
  • Documents: translating a document dispatches per-segment engine calls, bounded by a concurrency setting; translation-memory hits skip the engine entirely.
  • Evaluations: candidates and the LLM judge each resolve an engine, which is how two setups are compared side by side.
  • Glossaries: term extraction is a real engine call and is spend-capped; offline it still works against the deterministic mock.
  • Memory: memory only ever appears inside a prompt an engine receives.

Current limits#

Current limits

The offline mock is selected explicitly: choose Mock in Setup AI, or set the default provider to mock. On a configured install, a built-in provider with no key refuses to translate rather than silently degrading to placeholder output. A named engine profile that is misconfigured is refused loudly too, since it was an explicit choice.

Translation output that looks like placeholder text means the mock engine is active; the provider indicators in the interface show live versus mock at a glance.

A stored cloud key that no longer decrypts is treated as a dead engine rather than an empty one, and needs to be re-entered.

A spend cap, where configured, is a brake rather than a budget: it refuses new paid calls once reached. Local and mock calls are exempt.

A quality judge can only be a step's QE judge. Saving one as a project default, a language pair's provider, a step provider or fallback, or the install default is refused, and a hand-written reference to one in a translation slot fails loudly at run time. A hosted Jev engine's address cannot be changed.

A server started with a key needs the matching key on its engine, or every request fails authentication. If you save a Jev-compatible local server with no API key at a network address, Localization OS warns you: a server that accepts keyless requests can be used by anyone who can reach it, and they can see what is sent to it. Set a key on the server and add the same key to the engine.

Model output limits are real: a very long output is retried automatically with a larger budget up to the model's own ceiling, and then it fails honestly rather than truncating silently. A segment whose translation would not fit the engine's output limit in one answer is translated in pieces, cut at sentence ends, punctuation or spaces and never inside a tag or placeholder, then rejoined as one segment; one with nothing to cut at goes to review with the reason instead of failing the job.

Operator note for local reasoning models. Some reasoning models, for example a Gemma reasoning model, can spend their whole output budget on hidden reasoning and return no translation text. Localization OS recognizes that case rather than mistaking it for a cut-off translation: it retries once with reasoning turned off at the same budget instead of enlarging the budget, and for known reasoning models it turns reasoning off on the first call. If it still returns nothing, the run fails with a plain message that the model's reasoning consumed the output budget, rather than advising you to raise the output ceiling.

An optional, admin-only record of exactly what was sent to a model and what came back writes nothing at all while it is switched off. When it is on, its full request and reply bodies stay readable only by an administrator on the host, but a bodies-withheld summary, call counts, statuses, error classes, finish reasons, spend, and timings, with no prompt or reply text, is readable with a docs-scoped key over the API, the command line's remote mode, and the MCP server, scoped to your own organization.

A saved key belongs to the server it was saved for. Moving an engine's base URL to another server clears its saved key unless you enter a new one in the same save, and the move is recorded in the audit log. Base URLs with credentials embedded in them are refused; put credentials in the key field.

The spend cap exempts mock calls and local engines on loopback, private or tailnet addresses. A local engine on a public or unresolved address is priced and capped like any other.