Architecture.

One process, on purpose#

Localization OS ships as a modular monolith: one application, one relational core, running as a single process. There is no microservice mesh to operate and no message broker to keep alive. The boundaries that matter, between surfaces, between subsystems, and between the application and the infrastructure around it, are enforced in code, not by network hops. That keeps a self-hosted install simple to run: one process to start, one process to watch, one process to back up.

The same codebase scales when you need it to. A single node, a laptop, a VM, or an air-gapped box, is the whole story for most installs. When a deployment needs more, the same application runs behind PostgreSQL and a proxy, no rewrite required.

Four surfaces sit over one service layer. The core reaches your data through its named ports, and your chosen model through the same kind of swappable boundary.

Four surfaces, one set of services#

Every capability in Localization OS is reachable from up to four surfaces: a web UI for people, a REST API for integrations, a CLI for scripts and CI, and an MCP server for agents. The web UI, the API, and the CLI all call the same service layer directly; the MCP server calls through the API as a governed client, so it lands on the same service layer one step removed. Either way, a feature never becomes a second-class citizen on the surface nobody remembered to update.

That is a design rule, not a suggestion: a feature ships across the surfaces it applies to in the same change, with the real logic living once in a shared service and each surface acting as a thin caller. The practical effect for you: whatever you can do by clicking, you can do by scripting, and whatever an agent can do through MCP, a person can also do in the browser.

Kernel and ports#

Underneath the four surfaces sits a kernel: a facade that gives an embedder or an integrator one door into the application's services, without needing to know how they're organized internally.

At the edge of that kernel is a small set of named ports: identity, storage, scheduling, and telemetry, among others. Each port is an interface with a working default implementation, swappable without touching the code that calls it. Point storage at local disk or an S3-compatible bucket. Point identity at local accounts or an enterprise directory. Model access is swappable in the same spirit, an offline engine, your own endpoint, or a hosted provider, though by design it isn't implemented as one of the formal ports. Either way, the application itself doesn't change: only what's behind the boundary does.

The workflow engine#

At the center of the product is the workflow engine. A workflow is a sequence of steps, matching against translation memory and glossaries, machine or LLM-driven drafting, quality checks, and export, run against a batch of content as a run.

Any step can pause for a person: a human-review hold takes a run out of the automated path and puts it in front of someone who can approve, correct, or reject before the run continues. Delivery itself is gated the same way: content only leaves the system once it has cleared whatever checks the workflow defines for it, so "translated" and "ready to ship" are not automatically the same claim.

Data layer#

Localization OS stores its data in a single relational database. SQLite is the default: no database server to install, no connection string to manage, a working install out of one file. PostgreSQL is supported for installs that want a managed database server behind it, same schema, same application, no code change to move between them.

Offline first, live when you're ready#

A fresh install runs completely offline. The default translation engine is a deterministic mock: it produces real output through the real pipeline with no network calls and no API keys, so you can evaluate the whole system, workflows, review, export, before committing to a model provider.

Add a provider key when you're ready and the same install goes live, no code change and no re-deploy required. For teams that need translation to stay fully offline even in production, Localization OS also supports running models locally on a GPU you control, so content never has to leave the machine it's on.

Feature flags and the kill switch#

Core capabilities, documents, translation memory, glossary, workflows, budgets, and identity, are always on. Everything beyond that is individually toggleable, and switching one off is not merely a permission check: it takes effect the same way on every surface at once.

Most non-core features use full removal when switched off: the navigation entry disappears, the routes stop existing (answering as if the feature had never been built, not merely refusing it), the CLI commands refuse to run, and the API and MCP surfaces refuse the same way. A few features use a softer semantics instead: switching them off stops new writes while existing records stay readable, rather than pulling the whole surface down. Either way, the off state holds across every surface at once, with no corner where a disabled feature quietly keeps working.