Translations Editor

Where to find it

• Direct URL: /admin/translations
• From the sidebar: Admin → System section → Translations (right under Languages).
• From the Languages list: Admin → Languages → click the Translate button on any language row.

Prerequisites

The language you want to translate must first be registered in Admin → Languages. MailTrixy ships with 80+ pre-translated language files out of the box (French, German, Spanish, Romanian, Portuguese, Arabic, Hindi, Chinese, Japanese, and many more). You don't need to register a language for those — just go straight to the Translations editor and pick from the dropdown.

To add a NEW language not on the list: Admin → Languages → Add Language → enter the ISO code (e.g. fi for Finnish) and the name. After saving, you can translate it in the editor.

Editor layout

The page has three main sections:

• Top bar: Language picker dropdown, live progress bar (e.g. “3563 / 3659 strings translated, 97%”), Export button, Import JSON button.
• Sticky filter bar: Search input + filter pills (All / Missing / Translated) + visible-count + Save All button (disabled until you make edits).
• Strings table: Two columns — English source on the left (read-only), Translation textarea on the right (editable). Status pill at the end shows Translated / Missing / Same-as-source.

Translating workflow

1. Open /admin/translations.
2. Pick the target language from the dropdown.
3. Click the Missing filter pill to see only strings that need translation.
4. Type the translation into the textarea next to each English source string. As soon as you type, a yellow Edited badge appears next to that row, and the Save All Changes button activates with a count of unsaved edits.
5. Translate as many strings as you like in one sitting. Use the search bar to find specific strings.
6. Click Save All Changes. Only the rows you edited are sent (keeps the request small even on a 3,600-string file). On success, the progress bar updates, status pills flip to Translated, and a toast confirms.

Tip: The editor paginates 50 strings per page (~74 pages for the full 3,659-key file). Your unsaved edits are preserved across page changes — the dirty flag is on each row, not on the page. But your edits are NOT preserved across a browser refresh, so click Save All before refreshing.

Placeholder tokens (:variable)

Many strings contain placeholder tokens like :brand, :name, :count, :domain. You must preserve the placeholder verbatim in your translation, or it'll render literally in the UI instead of being substituted.

Example:

• English source: Complete these steps to get the most out of :brand
• French translation: Suivez ces étapes pour profiter pleinement de :brand  
• Wrong: Suivez ces étapes pour profiter pleinement de MailTrixy (loses the dynamic brand-name substitution)

Export & Import

Export

The Export button downloads the current lang/{code}.json file as it exists on disk. Useful for:

• Backing up before bulk edits.
• Sending to a professional translator who works offline.
• Committing to your own git repo if you self-host.

Import

The Import JSON button opens a modal where you can either upload a .json file OR paste raw JSON text. The import strategy:

• Only keys that exist in lang/en.json are accepted. Orphan keys (not in en.json) are silently dropped — you get a count of how many were ignored.
• Imported values overwrite any existing translation for those keys. Keys not in your import file are left unchanged.
• The file is written atomically with a file lock — safe even if another admin is editing the same language at the same time.
• A .bak backup of the previous version is saved before each import.

Safety

• File locking on every write (flock(LOCK_EX)) so two admins editing simultaneously cannot clobber each other.
• Automatic backup — lang/{code}.json.bak created before each save. One-step rollback by renaming back.
• Locale code sanitization — only letters, digits, hyphens, underscores allowed in the language code. Path-traversal-safe.
• Sorted keys — saved JSON uses the same key order as en.json for clean git diffs if you commit lang files to source control.
• Orphan key preservation — if your target file has keys that aren't in en.json (e.g. from a removed feature), they're appended at the end instead of silently dropped.