Translations — Reference
The Translations surface is the multi-language content plane for SGEN sites. It owns the per-locale strings for every translatable surface — page bodies, navigation labels, product descriptions, email templates, system messages — the fallback locale, the machine-translation pre-fill that seeds new locales, and the professional-translation handoff that exports strings for external review and reimports the result.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a localization program. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Translations lives under the Settings module in SG-Admin. The module renders four primary views — the locale list, the string-table editor scoped to a locale, the translation-coverage view that surfaces missing strings, and the handoff manager that owns export and reimport — and exposes a small set of write operations for add locale, edit string, machine-fill, mark verified, export bundle, and reimport.
The module is paired by convention: one half renders the views and prepares the string and coverage data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
A string is the unit of translation — one source phrase, one or more locale-specific renderings, optional context note for translators. Strings are keyed by a stable identifier; the source-language value is the canonical reference for translators. When a string is missing in a target locale, the front-end falls back to the configured fallback locale, then to the source-language value as the final fallback.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Settings → Translations
- URL prefix:
/sg-admin/translations/ - View templates:
application/views/Admin/Settings/Translations/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Settings → Translations [ + Add locale ] │├──────────────────────────────────────────────────────────────────────┤│ Locale Source Coverage Verified Last update ││ ─────────── ─────────────── ────────── ───────── ──────────────││ en-US canonical 100% 100% (source) ││ es-MX machine + edit 96% 84% 2 days ago ││ fil-PH machine 88% 12% 5 days ago ││ ja-JP professional 100% 100% 2 weeks ago ││ de-DE professional 74% 74% in handoff ││ ││ Total strings: 1,284 · Pending handoff: 1 (de-DE) ││ [ Edit table ] [ Machine-fill ] [ Export ] [ Reimport ] [ Verify ] │└──────────────────────────────────────────────────────────────────────┘Actions
The Translations surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List locales
Returns the locale registry, with locale code, source method (canonical, machine, professional, manual), coverage percentage, verified percentage, and last update timestamp. The fallback locale is flagged. Supports filter by source method, by coverage range, and by verification status.
View string table
Returns the full string set for a single locale, paginated, with key, source-language value, target-language value, verification flag, context note, and last-edit metadata. Supports filter by verified state, by missing-translation state, by context tag, and by free-text search across source or target.
Add locale
Registers a new locale. Required fields: locale code (BCP-47), display name, source method, initial coverage strategy. Optional fields: fallback locale (overrides the global default for this locale), region-specific currency, region-specific date format. On submit, the surface creates the empty string table for the locale, applies the initial coverage strategy (clone-from-source, machine-fill, or leave-empty), and returns the new locale identifier.
Edit string
Updates a single locale-specific value. Accepts the key, the new value, an optional context note, and an optional verification flag. On submit, the surface writes the new value, increments the locale's coverage if the slot was previously empty, and records the edit in the audit trail.
Bulk edit
Same shape as edit, scoped to a set of keys. Used when a phrase pattern needs to update across multiple strings simultaneously. The bulk write is atomic per-locale — either all writes succeed or all are rolled back.
Machine-fill
A dedicated write path. Reads the source-language values for a locale's empty slots and runs them through the configured machine-translation provider, persisting the results with verification flag set to false. Used to seed a new locale or to fill coverage gaps after the source language gains new strings. Machine-filled values are flagged distinctly so operators can verify them before treating them as canonical.
Engineering note. Machine-fill never overwrites a value with verification flag set to true. The verified state is treated as canonical even if the source-language string is updated downstream.Mark verified
Toggles the verification flag for one or more strings. Verified strings are treated as canonical and excluded from machine-fill overwrites. Used after a human reviewer confirms a machine-filled or professionally-translated value.
Export bundle
Exports a locale's strings in a translator-friendly format (XLIFF, JSON, or CSV depending on the configured handoff format). The export carries source value, target value (or empty), context note, and the key. Used for sending the locale to a professional translator. The handoff manager records the export timestamp and locks the strings against simultaneous machine-fill until reimport.
Reimport bundle
Accepts a translator-supplied bundle in the matching format. Validates the structure, writes the target values into the locale, sets verification flag to true for each touched string, and unlocks the strings from the handoff. Conflicts between the imported value and a recently-edited canonical entry are surfaced for review rather than overwritten silently.
Configure fallback locale
Sets the site-wide fallback locale used when a target-locale string is missing. Per-locale overrides may be defined under the locale record. On submit, the surface validates the fallback locale exists in the registry and updates the global setting. The change applies immediately to subsequent renders.
Archive locale
Marks the locale inactive without removing it from the database. Archived locales disappear from the front-end language switcher but remain queryable. Their string tables are retained for audit and for later restoration.
Data model
A locale record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
code | string | BCP-47 locale code. Unique. |
display_name | string | Operator-facing label. |
source_method | enum | canonical, machine, professional, manual. |
is_source | boolean | True for the canonical source locale. Exactly one. |
fallback_locale_id | integer | Optional override of the site-wide fallback. |
currency_code | string | Optional region default. |
date_format | string | Optional region default. |
status | enum | active, archived, in_handoff. |
coverage_pct | numeric | Cached. Recomputed on string write. |
verified_pct | numeric | Cached. Recomputed on verification toggle. |
created_at | timestamp | Set on locale add. |
updated_at | timestamp | Touched on string write. |
locale_id, key, source_value, target_value, is_verified, context_note, last_edited_by, last_edited_at, machine_filled_at. The key is stable across locales — the same key resolves to different values per locale.Handoff record: each export writes a row with locale_id, format, exported_at, exported_by, expected_return_at, reimported_at. Used to track in-flight handoffs and to detect overdue returns. While a locale is in handoff, machine-fill is disabled for that locale to prevent overwriting work-in-progress.
Resolution semantics: at render time, the front-end requests a string by key for the current locale. Resolution order is target-locale value → per-locale fallback (if set) → site-wide fallback → source-language value. The chain is cached per request; cache invalidation follows page-render cache rules.
RENDER REQUEST (key = "checkout.button.pay", locale = fil-PH)│▼┌────────────────────────────────────────────┐│ Resolver ││ ││ 1. lookup (fil-PH, key) ││ ├── value present → return ││ └── empty → step 2 ││ 2. lookup (fil-PH.fallback_locale, key) ││ ├── value present → return ││ └── empty → step 3 ││ 3. lookup (site_fallback_locale, key) ││ ├── value present → return ││ └── empty → step 4 ││ 4. return source_value │└──────────────────────┬─────────────────────┘│▼Rendered string│▼(cached for request)Permissions
Access to the Translations surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Translations surface.
Layer 2 — per-action capability. Within SG-Admin, each Translations action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List locales | ✔ | ✔ | ✔ |
| View string table | ✔ | ✔ | ✔ |
| Add locale | ✔ | — | — |
| Edit string | ✔ | ✔ | — |
| Bulk edit | ✔ | ✔ | — |
| Machine-fill | ✔ | ✔ | — |
| Mark verified | ✔ | ✔ | — |
| Export bundle | ✔ | ✔ | — |
| Reimport bundle | ✔ | ✔ | — |
| Configure fallback locale | ✔ | — | — |
| Archive locale | ✔ | — | — |
| Restore archived locale | ✔ | — | — |
Self-protection rules. The source locale cannot be archived — exactly one locale must always carry is_source = true. The site-wide fallback cannot be set to the same locale as the source (the fallback chain would loop). Reimport is rejected when the bundle's locale identifier disagrees with the file's declared locale; the surface returns a structured rejection naming the mismatch. Machine-fill is blocked while a locale is in handoff to prevent overwriting work-in-progress.
Audit. Every write — add locale, edit string, bulk edit, machine-fill, verification toggle, export, reimport, archive, restore — emits an Activity Log entry. The log records the acting operator, the locale identifier, the affected string key (or count for bulk operations), and the change shape. Reimport writes a separate entry per string overwritten by the bundle.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-protection rules │ archive source / fallback-loop /│ │ in-handoff machine-fill → reject└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entry + coverage recomputeRelated references
- Pages — Reference. Per-locale page bodies are stored as separate page records keyed to the locale. The string-table covers reusable phrases; page-body translation lives on the page record.
- Email Templates — Reference. Templates declare translatable slots that resolve through the Translations surface at send time.
- Products — Reference. Product names, descriptions, and option labels resolve through the string table when a non-source locale is active.
- Menus — Reference. Menu labels are keyed strings; the Translations surface owns the locale values. Adding a new menu item registers a new key in every locale's table.
- Settings — Reference. Owns the fallback locale, the machine-translation provider configuration, the handoff format default, and the audit-log retention window.
- Activity Log — Reference. Per-string edits surface here. Bulk operations write summary entries; per-string detail is available in the locale's audit view.
/docs/translations.