Architecture
Overview
Section titled “Overview”LokAI is structured around a clear hierarchy of concepts that map directly to how software teams organize their work.
Workspace
Section titled “Workspace”A Workspace is the top-level container for a company or team. Everything in LokAI belongs to a workspace: projects, glossaries, style guides, and tenants.
Project
Section titled “Project”A Project represents a single product or application being localized. Each project has:
- Main languages — the source language(s) that humans own and maintain
- Target languages — languages translated automatically by the LLM
- Secondary languages — additional human-maintained languages
Translation Key
Section titled “Translation Key”A Translation Key is a single translatable string. Keys carry rich metadata:
- A maintainer (the developer or team responsible)
- A description and context
- Per-language translations with ownership and status
- Flags (
do_not_translate,do_not_customize)
Glossary
Section titled “Glossary”A workspace-level Glossary defines preferred and forbidden terms. The LLM respects these rules in every translation it produces.
Style Guide
Section titled “Style Guide”A Style Guide is a Markdown document that instructs the LLM on tone, formality, capitalization, and product-specific conventions.
Tenants
Section titled “Tenants”Tenants are B2B customers who need custom terminology in their translations. Each tenant defines term replacements with natural-language context that the LLM interprets at translation time.
Access model
Section titled “Access model”LokAI uses a Permission / Role / Grant model.
- A permission is an atomic action such as
keys.createortranslations.approve. - A role is a bundle of permissions.
- A grant is the actual assignment of a role to a subject within a scope.
Current built-in roles:
owneradminproject_managerdeveloperdesignertranslatorreviewerviewer
Grants can be:
- organization-scoped: apply to the whole workspace
- project-scoped: apply only to one project
- language-filtered: limit only language-scoped actions such as writing or approving translations
Token subjects
Section titled “Token subjects”In addition to human users, LokAI supports machine identities:
- PATs (personal access tokens) are owned by one user and scoped to one workspace. Manage them across workspaces in Account → Access tokens (
/account/tokens). Choose the workspace when creating one. They must declare explicit scopes, can never exceed your current permissions, and are revoked when you leave their workspace. - WATs (workspace access tokens) belong to a workspace and outlive their creator’s membership. Admins manage them in Workspace Settings → Tokens (
/settings/tokens). They are intended for shared automation and are gated by permissions, capability, and quota checks.
Capability and quota gates
Section titled “Capability and quota gates”Authorization is not only about permissions. Some actions are also controlled by plan state:
- Capabilities decide whether a feature is enabled at all, such as workspace tokens or tenant customizations.
- Quotas decide whether a mutation can still consume capacity, such as creating another project or minting another PAT.
See Plans & Limits for the current matrix.
Ownership model
Section titled “Ownership model”Each project language has a role: main, secondary, or target. Each translation has an owner: human or llm. The LLM pipeline writes target-language translations and sets their owner to llm.
| Language role | Default owner | Who can write |
|---|---|---|
| Main | Human | translations.write_main, translations.write_main_secondary, or translations.write |
| Secondary | Human | translations.write_main_secondary or translations.write |
| Target | LLM | translations.write, plus translations.override_llm_ownership for LLM-owned rows |
- Editing a translation owned by
llmalso requirestranslations.override_llm_ownershipfor that language. Without it, the API rejects the edit. The check uses the translation’s owner, not the language role. - With the built-in roles,
translator,admin, andownercan write any language and override LLM ownership.developerwrites main languages only;designerwrites main and secondary languages. - A human edit to an LLM-owned translation keeps the owner as
llm. - Without write access, people can still comment, suggest, or approve, depending on their role.
Next steps
Section titled “Next steps”- REST API — current access and resource endpoints
- Plans & Limits — capability and quota matrix by plan
- LLM Pipeline — how AI translation works end to end
- Managing Translation Keys — working with keys in practice