Translator Workspace

Translator Workspace

The Translator Workspace at /translate lets community members translate the site without touching the repository. Users with the translator flag (granted directly by the superadmin via the Users tab, or by any Admin+ by accepting an application through the flow below) edit strings in their language, see the result live in a site preview, and submit edits for review. Admins approve or reject; approved edits go live immediately. A GitHub sync turns the accumulated approvals into a pull request so they survive into the next build.

Becoming a translator: the application flow

/translate is accessible to every logged-in user, not just active translators:

• Logged-out visitors see a brief overview of the program with login and register CTAs.
• Logged-in users without an application see an application form (or a "applications currently closed" message if the admin has disabled the toggle in the Pages tab).
• Applicants see a live status badge: Pending, Being Reviewed, Accepted, or Rejected (with the reviewer's reason if rejected).
• Accepted translators proceed to the full workspace as described below.

The application form collects:

• Target languages with proficiency level (Intermediate, Fluent, or Native); English proficiency is required as the source language.
• Motivation (required).
• Optional prior translation experience.
• Optional country of residence.

Admins review submissions from the Translator Apps tab in the admin panel and can Accept or Reject with a reason; see Admin Guide.

The workspace

The page has two cards:

• Preview card: a row of locale buttons (one per language other than English; hidden locales are dimmed and marked with an asterisk), a two letter code input plus Add button for creating a new locale, a Reload button, and an embedded iframe showing the live site rendered in the selected locale. The preview includes your own pending edits, so you see your work before anyone reviews it. Selecting a locale sets a tl_preview cookie so navigation inside the iframe stays in the previewed language; the server only honors that cookie for iframe requests from translator accounts.
• Editor card: a searchable list of every translation key with its English source text and the current translation. The filter dropdown narrows to All, Pending (your unreviewed edits), Untranslated (keys with no translation in this locale), or Rejected (your edits that were declined, with the reviewer's reason shown on the badge). Search matches the key name, the English text, the current text, and your pending text.

Submitting and withdrawing edits

Type your translation in a row's textarea and hit Save. The edit is stored as pending: it does not change the public site, but it does appear in your preview iframe. You can submit as many pending suggestions for a key as you like, each one is queued for review independently and shown in the row with its own Withdraw button. Edits are capped at 2000 characters and cannot be empty.

If a reviewer rejects an edit, the row shows a rejected badge with the reason. Submitting a new suggestion clears the rejection badge and adds the new edit to the pending queue.

Creating a community locale

Enter a two letter lowercase code and click Add. The locale registers immediately and is translatable right away, but it starts hidden from the public language switcher until an admin enables it in the admin locales panel. English (en) is the source language and can never be created or edited. Admins can later disable a locale again, or delete a disabled community locale (its overlay file is archived rather than destroyed, and pending edits are dropped while review history is kept).

Review (admin side)

Admins see the pending queue in the admin panel: each entry shows the translator, language, key, the English source, the previous text, and the proposed text. Two actions:

• Approve: the edit is applied immediately as a live overlay: the current overlay file is backed up, the new file is written atomically, and the in-memory store is hot reloaded. Only after the apply succeeds is the row marked approved, so a failed write never strands a half applied translation.
• Reject: requires a reason (up to 255 characters), which the translator sees in their workspace.

Admins can also download any locale's merged file (embedded strings plus approved overrides) as xx.json.

GitHub sync

Overlays live on the server's disk, so without action they would be lost when a new build ships with unchanged locale files. The sync button in the admin panel fixes that, implemented in internal/handlers/translate_github.go:

1. For every locale with at least one approved override, the merged bundle is committed to the translations branch under internal/i18n/locales/, skipping files whose branch content already matches. The branch is created from main if missing, and reset onto main when no sync PR is open so stale commits never pile up.
2. If anything changed and no sync PR exists, a pull request is opened from translations against main.

Only one sync runs at a time; a concurrent request gets a 409. Configuration is two environment variables (see Configuration):

• GITHUB_TOKEN: a fine grained personal access token with Contents and Pull requests read/write scopes on the one repository
• GITHUB_REPO, the target in owner/repo form

End to end flow of a contribution

1. A translator edits a string in the workspace; it becomes a pending edit visible only in their preview.
2. An admin approves it; the string goes live for everyone immediately as a disk overlay.
3. An admin runs the GitHub sync; the merged locale file lands on the translations branch and a PR opens against main.
4. The PR is merged; the repository's locale file now contains the translation.
5. The next build embeds it via go:embed; the overlay key is now identical to the embedded string and effectively retires.

See Localization for the underlying i18n machinery: lookup order, overlay semantics, and the UTF-8 without BOM requirement for locale files.