Scanning & CI
A scan is how your repo’s current state reaches Dialecto: the surgical slice, which is your catalog files plus optional code snippets. There are two ways for it to arrive. In Convenience mode the Dialecto GitHub App reads your translation files itself, at the paths you confirmed, and nothing needs wiring. In Security mode, or when you want code snippets (which only your CI can send), the scan runs on your infrastructure as one documented HTTP call, simple enough to wire into any CI in a few lines. This page is that contract.
The request
POST /api/repos/:repo_id/scans
Authorization: Bearer <scan token>
Content-Type: application/json
The scan token is per-repo, shown once at creation, stored only as a hash, and regenerable from the repo’s settings. It authorizes scanning — nothing else.
Payload
| Field | Required | Description |
|---|---|---|
gitSha |
yes | the commit the scan describes |
gitBranch |
yes | the branch — scans are branch-aware |
checksum |
yes | idempotency key; resending the same checksum is a no-op |
templates |
yes | array of {path, content} — your translation files (.po/.pot, or .json for a JSON project), verbatim bytes |
gettextUsages |
no | array of {file, content, start_line, end_line} — code snippets around gettext calls |
jsonUsages |
no | for a JSON project, where the code reads each key; the Astro add-on’s scan command builds it for you |
Paths must be relative paths inside the repository (no ..) that
match the project’s confirmed translation file paths; locale, domain,
and template-vs-catalog are derived from the path. For a Phoenix app
that means sending priv/gettext/** as-is after
mix gettext.extract --merge. JSON projects send their catalog files
the same way; the JSON guide covers what is
different, including the Astro add-on that sends where your code reads
each key.
Limits: 1,000 template files, 5 MB per file, 20 MB request body, 50,000 code snippets.
Responses
| Status | Meaning |
|---|---|
201 |
ingested — body includes entry/usage counts |
200 |
idempotent replay (same checksum), nothing changed |
401 |
bad or missing scan token |
413 |
over a size limit |
422 |
a template failed to parse — the whole scan is rejected, nothing partial is stored |
Parsing is strict on purpose: one malformed catalog rejects the scan,
so the index never holds a half-truth. Validate with msgfmt --check
locally if a 422 surprises you.
Asking what to scan
GET /api/repos/:repo_id/scan-config
Authorization: Bearer <scan token>
returns {scan_mode, branch_regex, tracked_branches} — so a CI job
can decide cheaply whether the current branch should scan at all.
scan_mode is a repo setting: selected (default — the branches you
track) or all (with an optional branch regex filter).
Follow-up work
Ingesting a scan fans out the follow-up work automatically: translation-memory capture from newly translated strings, re-publishing the merge gate and quality checks on affected PRs, and — if the repo opted in — the auto-translate pass over newly untranslated strings.
Security mode
In Security mode Dialecto holds no credential for your repository. The workflow Dialecto generates sends the translation files on every push, opens Dialecto’s pull requests and runs the translation check. Its two setup steps and its three jobs are under Security mode. After a push, the File access card shows the branch and commit of the last scan your workflow sent.
The scan token is shown once, and regenerating it stops the old one
straight away, so update the secret whenever you regenerate. A project
whose renames also rewrite code gets two files for its tooling/ folder
and a longer workflow, which applies the code changes on Dialecto’s
rename pull requests.
A CI recipe
Any CI works; the job is: check out, extract, build the payload, POST.
As a GitHub Actions sketch using only git, jq and curl, which the
runner image already has (adjust the paths to your catalogs):
- uses: actions/checkout@v6
- run: mix gettext.extract --merge
- name: Send the scan
env:
DIALECTO_SCAN_TOKEN: ${{ secrets.DIALECTO_SCAN_TOKEN }}
DIALECTO_URL: https://app.dialecto.eu
DIALECTO_REPO: "<your project ID>"
run: |
set -euo pipefail
paths=(':(glob)priv/gettext/**/*.po' ':(glob)priv/gettext/**/*.pot')
git ls-files -z -- "${paths[@]}" | while IFS= read -r -d '' file; do
jq -cn --arg path "$file" --rawfile content "$file" \
'{path: $path, content: $content}'
done > "$RUNNER_TEMP/templates.jsonl"
checksum=$({ printf '%s\n%s\n' "$GITHUB_SHA" "$GITHUB_REF_NAME"; \
git ls-files -s -- "${paths[@]}"; } | sha256sum | cut -d' ' -f1)
jq -s --arg sha "$GITHUB_SHA" --arg branch "$GITHUB_REF_NAME" \
--arg checksum "$checksum" \
'{gitSha: $sha, gitBranch: $branch, checksum: $checksum, templates: .}' \
"$RUNNER_TEMP/templates.jsonl" > "$RUNNER_TEMP/scan.json"
curl -sS --fail-with-body --retry 3 -X POST \
-H "Authorization: Bearer $DIALECTO_SCAN_TOKEN" \
-H "Content-Type: application/json" \
--data-binary "@$RUNNER_TEMP/scan.json" \
"$DIALECTO_URL/api/repos/$DIALECTO_REPO/scans"
The checksum covers the commit, the branch and every sent file’s blob
id, so a re-run is a no-op and a revert still counts as a new scan.
If you run Dialecto yourself, use your own host instead of
app.dialecto.eu. The project ID is shown in the
project’s settings, on the Scan token card.
Rate limiting applies to scan uploads (HTTP 429 with a retry-after
header, at 30 uploads a minute per IP address); one scan per push is the
intended cadence.
The source-rewrite action
Separate from scanning: when a Dialecto PR carries
call-site rewrites, a repo-side action applies
them against your working tree, touching only the rewrites listed in
the PR. Dialecto computes those rewrites today. The action,
dialecto-eu/source-rewrite, is public on GitHub at
github.com/dialecto-eu/source-rewrite.
Reference it as dialecto-eu/source-rewrite@v1, or pin it to a release
commit. In a repository without the action, the PR lists every call site
as a manual follow-up instead.