Concepts

Six ideas explain almost everything Dialecto does. Once they click, the rest of the docs are details.

Your repo is the source of truth

Dialecto never becomes the home of your strings. Your translation files (.po/.pot for gettext, JSON message files for JSON projects) stay in your repository; Dialecto holds an editable index of them — a queryable, reviewable working copy built from your scans — and every change flows back as a pull request you merge like any other. If you stop using Dialecto, you lose nothing: the catalog in your repo is current as of your last merged PR.

The surgical slice

A scan carries exactly two things: your translation catalogs (verbatim bytes) and, optionally, the small usage snippets around each gettext call. Not your application code, not your history, not your whole repo. By default the Dialecto GitHub App reads only the translation files; if you block read access, your CI sends them instead. Usage snippets only ever arrive from your CI. They power in-place context (seeing where a string lives while translating) and the call-site rewrite.

Domains

Gettext already organizes strings into domains — default, errors, emails, whatever your app has grown. Dialecto makes that the primary editing structure: browse a domain, translate a domain, and when the naming has drifted, rename keys in batch — each rename carrying its call sites with it. Entries can be added and deleted; the structure your app already has is the structure you edit in.

The minimal diff

Dialecto parses your files but never regenerates them. Edits are byte-precise splices into the original file content: change one translation, and the diff is that one line. Comments (translator comments, extracted comments, references, flags, previous-msgid markers, obsolete entries), ordering, and wrapping all survive untouched. That’s what makes a translation PR reviewable — and it’s the property the merge gate and your reviewers can trust.

The review lifecycle

Changes move through explicit states: staged → submitted → reviewed → approved → batched into a PR. Roles decide who can do what (translators can be scoped to specific locales; see the reference for the full matrix). Comments attach per entry, an attributed activity trail records who did what, revision history lets you step any entry back, and notifications (in-app and email) keep reviewers unblocked.

Two safety nets run underneath:

• Validation — placeholder parity, plural forms, glossary consistency — flags problems while you type, not after you ship.
• Stale-base detection — if a new scan changes a string you have a pending edit against, the conflict is surfaced instead of silently merged. Scans are authoritative; your stale edit is flagged, never guessed about.

Branches

Scans carry their branch, so Dialecto knows your base catalog from your feature branches. Feature branches get their own editable catalog view; edits there are branch-scoped and ship as pull requests into that branch, so localization can ride along with the feature instead of trailing it. The merge gate evaluates PRs against this same model — in its default incremental scope, only gaps a PR newly introduces count against it.