Getting started
This walkthrough follows a repository from its first scan to its first translation pull request. It assumes a gettext project; Elixir/Phoenix is the polished path (see the Elixir guide). JSON message files work the same way, and the JSON guide covers what is different.
Dialecto is in a soft launch, so details may still change as we finish it. Accounts are open: sign up free and follow the steps below with your own repository.
1. Account
You sign in with your email. Dialecto’s authentication is self-hosted: a magic link to sign in, and a password if you prefer one. Your account belongs to an organization, and repositories are worked on by teams. When you register, Dialecto creates a personal organization and a default team for you, so you can start on your own and invite people later. In the app a repository is called a project, and the docs use both words for the same thing.
2. Repository connection
From Projects → Connect a project, enter the repository’s address, choose the team that will work on it, and choose its catalog format (gettext, or JSON message files). Then choose how Dialecto reaches your repository:
- Convenience, one step. Install the Dialecto GitHub App and you are done. Dialecto reads your translation files and opens pull requests for you. An owner or admin connects the app once for the organization and then links it to each project. Where your Dialecto server has no app, a fine-scoped personal access token takes its place.
- Security, two steps. Add a workflow file and a secret to your repository. Dialecto gets no access to it; your pipeline sends the files and opens the pull requests.
You can switch a project later on its File access card. GitHub App covers both modes in full.
Security mode setup
- Scan token. On the File access card, choose
Generate scan token and save the scan token in GitHub as the
repository secret
DIALECTO_SCAN_TOKEN. Dialecto shows it once and stores only a hash. - Workflow. Commit the workflow Dialecto generates as
.github/workflows/dialecto.yml. On every push it sends your translation files and opens the pull requests Dialecto queued, and on pull requests it runs theDialecto/translationscheck. In the repository’s Settings, under Actions → General, turn on Allow GitHub Actions to create and approve pull requests.
3. First scan
A scan carries your catalogs and, optionally, the code snippets around each gettext call, which power in-place context and the rename rewrite. Nothing else leaves your repo.
In Convenience mode a push to a scanned branch is enough, because Dialecto reads the translation files itself. In Security mode your workflow sends them on that push. To add code snippets, your CI sends the scan. For an Elixir project:
mix gettext.extract --merge
# then POST priv/gettext/** to Dialecto, as described in the scan reference
The scan is one authenticated HTTP call. The full payload contract, the limits and a CI sketch live in Scanning & CI.
4. Catalog
Open Projects → your project → Catalog. Your strings appear organized by domain, each entry with its translations per locale and, if your scan sent code snippets, the code around it. This is the editor; Concepts explains the model behind it.
5. Edits and the diff
Translate a few strings. Every save stages a change, and the staged set previews as a minimal unified diff: one line per change, with comments and ordering untouched. Validation runs as you go, covering placeholder parity, plural forms and glossary terms.
6. Review and merge
Submit staged work for review (or approve it yourself if your role allows), then open the pull request. In Convenience mode Dialecto commits through the GitHub API without cloning, and with the App installed the commit is app-attributed and Verified. In Security mode the pull request opens the next time your workflow runs. Merge it on GitHub like any other pull request.
Next steps
- The merge gate makes missing translations block merges.
- Context & personas gives the AI your voice.
- Scanning & CI covers the scan contract for your CI.
- API & MCP connects your editor or coding agent.