START HERE FEATURE
Locale Setup
Locale should become a boring, explicit part of project setup: pick the default, declare supported locales, add JSON catalogs, and verify one translated string end to end.
Feature Guide
A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.
What this does
Configure the minimal Locale contract so translations and locale-aware rendering become explicit early.
Locale Baseline
Add the smallest locale setup that is still real
Declare the locale boundary in `.env`, add one JSON file per language, render one translated string through Twig, and restart once so the catalogs reload cleanly.
Step 1
Declare the locale contract in `.env`
Keep the first setup tiny. You usually need only the default locale, fallback locale, supported locales, and whether locale prefixes belong in URLs.
LOCALE_DEFAULT=enLOCALE_FALLBACK=enLOCALE_SUPPORTED=en,ukLOCALE_URL_PREFIX=falseStep 2
Add one JSON catalog per language
Locale files are module-local. Start with one or two keys, not a giant spreadsheet dump.
src/Application/View/locales/en.json{"ContactForm.title":"Contact us","ContactForm.submit":"Send"}src/Application/View/locales/uk.json{"ContactForm.title":"Zvjazhit`sja z namy","ContactForm.submit":"Nadislaty"}Step 3
Render and verify one translated string
Use `trans()` in Twig, restart once so the worker reloads catalogs, then verify the output through the locale path or request headers.
{{ trans('ContactForm.title') }}bin/semitexa server:restartcurl -H 'Accept-Language: uk' http://semitexa.testhttp://semitexa.testImportant Defaults
- If you installed from `semitexa/ultimate`, the locale package is already part of the baseline stack.
- JSON locale catalogs are loaded at worker boot, so restart or reload after editing them.
- Turn `LOCALE_URL_PREFIX=true` on only when you really want locale-prefixed URLs like `/uk/...`.
- Keep keys module-scoped from day one. `ContactForm.title` ages much better than `title`.
Verified against Semitexa Ultimate 2026.09.19.1020
Locale Setup
Semitexa keeps locale as an explicit contract. Even when phase 1 ships English-only documentation, the runtime should still make locale handling visible and deterministic.
Canonical flow
- Define the default locale.
- Declare supported locales.
- Wire translation catalogs.
- Verify one translation in Twig so the path is proven.
What to preserve
- locale resolution remains explicit
- fallback behavior is deterministic
- translation keys do not turn into scattered string guesses
Why this matters
Multilingual support is easiest to preserve when the first locale setup is explicit, even if only English content is active at the beginning.