Core Concepts

Organization : A tenant that owns projects and has members with roles. The top-level grouping in Lokalio.

Project : A translation project belonging to one Organization. Contains project-level configuration: source language, target languages, AI context, tone guidelines, and glossary.

Repository : A Git repository (GitHub or GitLab) linked to a Project. Multiple repositories can belong to one Project. Contains the translation files that trigger CI translation jobs.

API Key : A scoped credential issued at the repository level. Used by the CLI and CI for authentication. Currently all keys have read/write translation permissions.

Translation Concepts

Translation String : A single source-language key-value pair extracted from a file.

Translation Batch : A set of Translation Strings sent to the API for AI translation. Batched by the CLI in chunks of ~100 strings.

Placeholder : A variable in a translation string (e.g., {{name}}, {count}, %s, <0>text</0>) that must be preserved verbatim through translation. Handled via extract-reinsert — the CLI extracts placeholders before sending to the API and reinserts them after.

Modes

Diff Mode : Translation mode that detects changed keys by running git diff against the base branch and translating only added or modified strings. Default mode. Best for ongoing development.

Add/Remove Mode : Translation mode that scans source files and translates any keys present in source but absent from target files. Best for bootstrapping new languages.

Configuration

AI Context : Per-project information used to improve translation quality. Includes project description, tone guidelines, custom AI instructions, and a glossary of approved term translations. Can be overridden per-run via a context.yaml file.

Glossary : A list of source-language terms with approved target-language translations. The AI respects these when translating. Can be defined inline in .lokalio.yaml or referenced from an external file.

.lokalio.yaml : The project configuration file committed to the repository root. Defines source/target file mappings, platform (GitHub/GitLab), repository slug, glossary reference, mode, and optional context file reference.

CI / Workflow

CLI : The client-side command-line tool (lokalio) that parses translation files, sends strings to the API, and merges returned translations back into target files.

CI Action : A GitHub Action (or GitLab equivalent) that automates the translation workflow within a CI pipeline.

Scaffold (init) : The lokalio init command that interactively creates .lokalio.yaml and the appropriate CI workflow file.

Translation Branch : A dedicated branch named lokalio/<source-branch-slug> created by the CLI/Action. Contains translated target files. Force-pushed on each run. Serves as the head of the translation PR.