Skip to content

Architecture

LokAI is structured around a clear hierarchy of concepts that map directly to how software teams organize their work.

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.

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

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)

A workspace-level Glossary defines preferred and forbidden terms. The LLM respects these rules in every translation it produces.

A Style Guide is a Markdown document that instructs the LLM on tone, formality, capitalization, and product-specific conventions.

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.

LokAI uses a Permission / Role / Grant model.

  • A permission is an atomic action such as keys.create or translations.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:

  • owner
  • admin
  • project_manager
  • developer
  • designer
  • translator
  • reviewer
  • viewer

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

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.

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.

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 llm also requires translations.override_llm_ownership for 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, and owner can write any language and override LLM ownership. developer writes main languages only; designer writes 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.