Language translations

Shipped locales

Files live under `lang/*.json`. On install (and on Admin → Languages → Sync), Hirevia creates matching Languages rows and loads those catalogs into the database.

Code	Language	File
`en`	English (default)	`lang/en.json`
`de`	German	`lang/de.json`
`es`	Spanish	`lang/es.json`
`fr`	French	`lang/fr.json`
`hi`	Hindi	`lang/hi.json`
`it`	Italian	`lang/it.json`
`nl`	Dutch	`lang/nl.json`
`pt-pt`	Portuguese (Portugal)	`lang/pt-PT.json`
`ru`	Russian	`lang/ru.json`
`tr`	Turkish	`lang/tr.json`

English is the source of truth for new keys. Non-English shipped files may lag a few keys after a release — Sync fills missing keys from English without overwriting custom edits. Untouched English placeholders in a non-English locale are upgraded from the shipped file when Sync runs.

How it works

lang/en.json  (shipped English catalog)
      ↓ sync / seed
languages.messages in the database  (per locale overrides)
      ↓
LanguageService → Inertia props (i18n)
      ↓
Vue useI18n().t('key', 'fallback')  /  PHP LanguageService::text()

Runtime messages merge as: English file → shipped locale file → database. The active locale comes from the `locale` cookie (or the default language).

Marketing page sections and navigation labels also register `marketing.*` keys into the same catalog when you save the customizer.

Layer	Role
`lang/*.json`	Shipped catalogs for new installs and Sync
Database	Buyer edits under Admin → Languages (wins over the catalogs)
Marketing customizer	Locale picker writes the active locale; keys are added to every language
Cookie `locale`	Visitor’s chosen language
Default language	Used when there is no cookie; customizer opens on this locale

info

Editing a string in Languages updates the live site. Syncing never overwrites values you already customized — it adds missing keys and can upgrade untouched English placeholders from a shipped locale file. Marketing keys are registered from the page/nav customizer the same way (add-missing only on other locales).

Admin → Languages

URL: `/admin/settings/languages` (permission: manage languages).

Action	What it does
Add language	Code (`en`, `fr`, `pt-br`, …), English name, native name, enabled, optional default. If a shipped `lang/{code}.json` exists, that catalog is used; otherwise optional DeepL fill from English
Translate on create	DeepL bulk fill from English when no shipped file exists (needs DeepL key)
Edit	Tabs by key group (`admin`, `auth`, `nav`, `marketing`, `interview`, `finance`, …)
Sync language	Ensure shipped locale rows exist; pull new keys / shipped upgrades into every locale
DeepL settings	Driver `none` or `deepl` + API key
Delete	Allowed except for English and the current default

English stays enabled. Setting a language as Default forces it enabled and clears other defaults. Only enabled languages appear in the visitor switcher.

info

After adding new lang/*.json files in an update, open Admin → Languages (or click Sync) so the new locales are created and catalogs load. Then flip the switcher — UI chrome should change immediately.

Marketing customizer

Admin → Marketing → Pages (and Navigation):

• Opens on the site default language.
• Change Content language to edit another locale’s copy.
• Default language: Save draft keeps a private draft (public site unchanged). Publish writes CMS + language keys.
• Other languages: Save/publish writes that locale’s Languages entries (and registers missing keys on every language) without changing the CMS source body.
• Layout / structure changes (add section, reorder, nav structure) apply when saving/publishing in the default language.
• The same keys appear under Languages → marketing for bulk edit / DeepL.

Blog articles stay free-form CMS HTML and are not keyed into Languages.

Visitors

• Language switcher on marketing, auth, and app chrome.
• Choosing a language posts to `/locale` and sets a long-lived cookie.
• Only enabled languages appear in the switcher.
• Marketing page bodies and nav labels resolve from the active locale with CMS English as fallback.

Practice content languages (separate from UI)

Three different “languages” stay distinct:

Kind	Where	Drives
UI chrome	Cookie + Languages catalog	Buttons, nav, settings
Interview session	Lobby picker on text / voice / video	Interviewer prompts, evaluation, AI report narrative
Practice packs	One-way / question bank `translations` JSON	Pack/bank prompts shown for that run

Live interviews: the lobby language defaults to the UI locale but can be changed. That choice is stored on the session and frozen onto the report. Changing the site language later does not rewrite an old report.

Answer bank: STAR split detects the story language and returns STAR fields in that language (no separate translation storage).

Practice pack/bank bodies live on the entity (`translations` / `published_locales`), not in the Languages catalog. Target locales match the same interview language catalog as the lobby (not only UI Languages).

Admin: translate → review → publish

Requires DeepL under Admin → Languages. Without a key, admin shows a CTA to open Languages.

1. Generate or write English — AI and manual edits always land in the English source columns.

2. Translate — From Admin → Question practice or Admin → One-way:

   - Per row: Translate (pick one or more targets).

   - Toolbar: Translate missing or Translate all (optionally limited to selected rows).

3. Background job — Translation is queued (`ShouldQueue`). The admin gets a success toast immediately and does not wait for DeepL. A queue worker must be running Cron Job.

4. Review — Switch Content language to a draft locale (English plus locales that already have drafts). Edit that locale’s copy; English remains the DeepL source.

5. Publish / unpublish one language — With a non-English content language selected, the action is Publish {Language} or Unpublish {Language} for that locale only. English is always the source and is not “published” separately. Users only see published locales.

Question practice: publish from the bank detail page (content language toggle). One-way: publish from the packs list using the same content language toggle.

Candidates: pick language, then lock

• A Language column appears when the bank/pack has more than English published.
• Changing the picker updates the displayed name/role for that locale immediately.
• Default preference follows the UI locale when that locale is published; otherwise English.
• Starting a run stores the chosen language on the run. While the run is in progress, language cannot be changed (shown as text). Retake can pick again.
• Evaluation and the report narrative use the run language.

See also Question practice overview and One-way overview

What is translated

In Languages	Not in Languages
App shell, admin, auth, onboarding, nav chrome	Blog article HTML bodies
Billing UI labels, plugin chrome	User answers, transcripts, frozen report narratives
Marketing page section copy + nav labels (`marketing.*`)	One-way / QP pack bodies (entity `translations`)
	Raw API / license-server errors

Plugins do not ship separate language files. Their UI keys live in the same `lang/*.json` / Languages catalog.

DeepL (optional)

1. Admin → Languages → DeepL — set driver to DeepL and paste your API key.
2. When adding a UI language with no shipped file, enable translate to prefill from English.
3. The same key powers practice content translate actions (Question practice / One-way).
4. Placeholders like `{persona}` are preserved during UI translation.

warning

DeepL is BYOK. Hirevia does not include DeepL credits. Review auto-translated strings (UI and practice drafts) before publishing / going live. Practice translate jobs need a running queue worker.

Tips after an update

1. Open Admin → Languages and run Sync so new UI keys and any new shipped locales appear.
2. Review or translate new strings for each enabled locale (shipped files cover the defaults).
3. Keep English as the fallback — missing keys fall back to the catalog / CMS copy.

Install already seeds Languages and registers marketing keys. Buyers on shared hosting do not need CLI commands for that — Sync in the admin UI is enough after updates.