Languages
Manage UI languages, translation strings, JSON import/export, and the default locale.
Overview
Languages manages UI locales: activate languages, edit translation strings, import/export JSON, and set the default language.
Where it lives
Route: /admin/settings/languages (admin.settings.languages)
Open Admin → Data → Languages.
Permissions
| Ability | Used for |
|---|---|
languages.view |
View the page |
languages.manage |
Add/edit/delete languages, edit strings, import/export, set default |
Key workflows
- Add language — code, name, native name, optional copy-from, active flag
- Edit strings — paginated inline editor with search and untranslated-only filter
- Download / Upload JSON — non-English languages; upload must map English source → translation
- Set default — full page reload so chrome locale updates
- English cannot be deleted, deactivated, or overwritten via upload in the UI
Translation backfill workflow
JSON seed packs under database/seeders/data/lang/{locale}.json are the source of truth for the seven non-English locales (en-srf, fr, de, it, es, pt, zh). The living TARGET is the current English (en) key set in the database — never a hardcoded count. Two orphaned tax labels (Tax Label, Default Tax Rate (%)) sit only on non-English rows and fall outside that set.
When new UI copy lands:
- Add the
__('...')/@lang/->label()/#[Title]call in code. - Run
php artisan signals:lang:sync(additive). Do not pass--pruneunless you intend to drop stale stored keys. - Inspect the gap:
php artisan signals:lang-backfill {locale} --dry-run(or--all --dry-run). Dry-run writes nothing and calls no AI provider. - Fill missing pack entries:
php artisan signals:lang-backfill --all --report=storage/lang-backfill-report.json. Run it while someone can review the output — not unattended against live providers. Existing non-empty pack entries are never overwritten; re-runs skip already-filled keys. - Load packs into the database:
php artisan db:seed --class=LanguageTranslationSeeder(idempotent; never overwrites a non-null value). - Confirm coverage:
php artisan signals:lang-coverage --fail-under=100compares each pack to the live extractor set.
--report writes per-key source/target plus flags (length_outlier, placeholder_mismatch, looks_english). Add --spot-review to restrict that report to navigation, rental statuses, availability, and email/document template keys. --batch=50 controls how many keys go to the provider per request; lower it if a locale's keys are long enough to strain a single call.
What a real backfill needs
signals:lang-backfill calls Anthropic through the AI SDK. A dry run needs nothing, but a real run needs ANTHROPIC_API_KEY set in the environment — the command pins that provider and has no local fallback. This is separate from the AI provider used for embeddings, which is configured through SIGNALS_AI_* and never uses Anthropic.
Why a key can still be empty after a successful run
Model output is validated before it reaches a pack, and anything that fails is dropped rather than written:
- a translation whose placeholders do not match the source key's (
:name,:count, and friends); - a translation that introduces HTML attributes the English source does not have.
So a run can report success and still leave keys missing. Re-running is the fix — filled entries are skipped, so only the rejected keys are retried.
When 100% is unreachable
signals:lang-coverage compares each pack to the live extractor key set. If code contains __() strings that have never been synced into the database, no pack can reach 100% and the command says so explicitly, pointing you back at php artisan signals:lang:sync (without --prune). Treat that warning as a missing step 2, not a translation problem.
The coverage floor is enforced in CI
A Pest test runs signals:lang-coverage at a 100% floor, so shipping a new __() string without carrying it through the workflow above fails the suite. All seven non-English packs currently ship at full coverage; the floor exists to keep them there.