Soft launchDialecto is still in testing, and details on this site may change as we finish it.

GitHub App

Each project picks one of two access modes, and you can switch it later on the File access card of the project’s settings.

  • Convenience. Install the Dialecto GitHub App and you are done. Dialecto reads your translation files and opens pull requests for you.
  • Security. 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.

In Convenience mode Dialecto talks to GitHub for three reasons: reading your translation files, opening pull requests with your approved translation changes, and publishing the merge-gate checks on pull requests. It never clones your repository for any of them. In Security mode it doesn’t talk to your repository at all, and your workflow does all three jobs (see Security mode).

The GitHub App

The Dialecto GitHub App is the preferred connection. Its permission set is deliberately small:

Permission Access Purpose
Contents Read & write read your translation files, and commit translation changes to a branch
Pull requests Read & write open the PR
Checks Read & write publish Dialecto/translations / Dialecto/quality
Metadata Read GitHub’s baseline for any App

GitHub grants the Contents permission for the whole repository, not for single paths. Dialecto’s own code limits what it reads to the translation files at the paths you confirmed, and it never reads your source code. In Security mode Dialecto holds no credential for the repository, and your own workflow decides which files reach it.

It subscribes to push events, which is how Dialecto reads the pushed commit’s translation files, to pull-request events (opened, synchronize, reopened, and merged), which is what re-runs the gate checks when a PR changes, and to installation and repository events, which keep the links between your projects and their repositories true. Webhook deliveries are HMAC-verified before anything is processed.

Commit attribution

Dialecto commits via GitHub’s API (createCommitOnBranch) — there is no clone and no push. With the App installed, commits are attributed to dialecto[bot] and show as Verified, because GitHub signs API-created commits itself. Your history shows plainly which changes came through Dialecto.

Installing

An organization owner or admin chooses Connect GitHub on the organization page, which sends you through GitHub’s install flow and back; installation is per GitHub account or organization, and you choose which repositories it may see. Then, in the project’s settings, the GitHub connection card has Link to the Dialecto GitHub app, which ties that project to its repository.

Personal access token

If your Dialecto deployment doesn’t have the App configured (or you prefer not to install one), a repo can connect with a fine-scoped personal access token instead. The token is encrypted at rest with a key held separately from the application secret, and only its last four characters are ever displayed again. Commits made this way are attributed to the token’s user.

Prefer the App where available, because it gives you short-lived installation tokens, bot attribution and Verified commits.

Security mode

In Security mode Dialecto holds no credential for your repository. A workflow you commit sends the translation files it names, opens Dialecto’s pull requests with your repository’s own GITHUB_TOKEN, and runs the translation check. Only the paths listed in that file can reach Dialecto or change in a pull request, and your repository enforces that. Setup is two steps, both on the project’s File access card under Security setup.

  1. Scan token. Choose Generate scan token, then save the scan token in GitHub as the repository secret DIALECTO_SCAN_TOKEN, under Settings → Secrets and variables → Actions. Dialecto shows it once.
  2. Workflow. Commit the workflow Dialecto generates as .github/workflows/dialecto.yml. It carries your project ID and your confirmed paths, and for translation files alone it uses only git, jq, curl and gh from GitHub’s runner image. In the repository’s Settings, under Actions → General, turn on Allow GitHub Actions to create and approve pull requests, so the workflow can open Dialecto’s pull requests. GitHub leaves it off for new repositories.

The workflow runs on every push, on pull requests, and when you choose Run workflow on GitHub. It has three jobs.

Job Trigger Work
send every push Sends the pushed commit’s translation files to Dialecto, on the branches the project scans.
open-pr every push, after send Opens the pull request Dialecto queued on a dialecto/ branch, writing only files under its paths, and posts the Dialecto/translations check on it.
gate pull requests Sends the branch’s translation files and reports the Dialecto/translations check, which fails when a required locale is missing a translation.

Make Dialecto/translations a required status check in branch protection. Your own pull requests get it from the gate job, and Dialecto’s pull requests get it from the open-pr job.

When you open a pull request in Dialecto, it waits in a queue until the workflow next runs, which is your next push, a click on Run workflow (Dialecto links to it), or a schedule you turn on in the file. Commits come from github-actions[bot]. GitHub starts no other workflows for a pull request opened with the repository’s own token. To run your other checks on it, close and reopen it.