SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

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:

  1. Add the __('...') / @lang / ->label() / #[Title] call in code.
  2. Run php artisan signals:lang:sync (additive). Do not pass --prune unless you intend to drop stale stored keys.
  3. Inspect the gap: php artisan signals:lang-backfill {locale} --dry-run (or --all --dry-run). Dry-run writes nothing and calls no AI provider.
  4. 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.
  5. Load packs into the database: php artisan db:seed --class=LanguageTranslationSeeder (idempotent; never overwrites a non-null value).
  6. Confirm coverage: php artisan signals:lang-coverage --fail-under=100 compares 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.