Getting started.

What you need#

Localization OS is a single application: one process, no Node build step, no cluster to stand up. Pick whichever of these you already have on hand.

• Docker, if you want the fastest path to a running instance, or
• Python 3.10 or newer, if you would rather run it directly and read the code as you go.

Either way, nothing here needs a provider account or an API key: an offline mock engine ships with the product and runs with zero keys, once you select it (see Run your first translation below).

Install#

Two starting points. Use whichever fits your workflow; first login differs between them (below).

Option A: Docker

docker compose up -d --build

This brings up the application on SQLite with no external services required. A Postgres profile and a TLS reverse-proxy profile are also available; see the deploy guide for a server setup.

Option B: Plain Python

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
cp .env.example .env
.venv/bin/python run.py

On Windows, the equivalents are .venv\Scripts\python.exe in place of .venv/bin/python, and copy in place of cp.

Once it is running, open the app in your browser at the address the terminal prints (by default, port 8000 on your own machine).

First login#

Option B, plain Python: a local development install seeds demo accounts, spanning admin and non-admin roles, so you can sign in immediately and look around without creating anything by hand. Change their passwords from the account page, and never expose a local development install to a network.

Option A, Docker: the compose file declares this a real server install, so the login wall is on and no accounts are seeded. Your first visit lands on a setup page to create the real admin. The deploy guide covers that path in detail.

Run your first translation#

Every translation in Localization OS runs through the same pipeline, whether it is powered by a real model or not. A deterministic offline mock engine ships with the product: it produces a complete, real run, with translation memory, glossary matching, and quality checks all exercised, and it costs nothing and needs no key. It has to be selected, though: .env.example configures a real cloud provider by default, and a configured provider with no key refuses to translate rather than quietly falling back to the mock.

1. Switch to the offline mock before your first run: pick Mock on the Setup AI page, or set DEFAULT_PROVIDER=mock in .env before you start the app, or run it from the CLI against a running install (.venv/bin/python -m app.cli config set default_provider mock; on Docker, docker compose exec app python -m app.cli config set default_provider mock).
2. Create a project and upload a document, or a small test file, to translate.
3. Pick a workflow and a target language, and start the run.
4. Watch it complete, then open the result in the editor.

When you are ready to translate for real, add a provider key (an LLM provider, a dedicated MT engine, or a local model server) on the setup page. No code changes are needed: the next run for that engine simply goes live.

Where to go next#

From here, three paths cover most of what people want next:

• Deploy, for a real server install: Postgres, a TLS proxy, and the container conventions.
• Features, for a page-by-page reference of everything the product does.
• CLI, for driving Localization OS headlessly, from a terminal or from CI.