README

Translation for the Scafera framework. UI string translation with locale management, RTL support, and Twig integration.

Internally adopts symfony/translation. Userland code never imports Symfony Translation types — boundary enforcement blocks it at compile time.

Provides: UI string translation for Scafera — Translator for lookup, LocaleManager for locale switching (with RTL detection). Flat JSON translation files with {name} parameter syntax (not Symfony's %name%). When scafera/frontend is installed, a companion bundle registers {{ t() }} and {{ locale_direction() }} Twig functions automatically.

Depends on: A Scafera host project whose architecture package defines a translations directory via getTranslationsDir() (e.g. resources/translations/ in scafera/layered). Twig integration activates only when scafera/frontend is installed.

Extension points: None of its own — Translator and LocaleManager are consumed as services. New locales are picked up by adding {locale}.json files to the translations directory. Locale behavior is tuned via two parameters in config/config.yaml: scafera.translate.default_locale and scafera.translate.rtl_locales.

Not responsible for: Non-JSON translation formats (no YAML, no XLIFF — deliberate) · multi-level fallback chains (single fallback to default locale only) · choosing the translations directory (architecture package owns getTranslationsDir()) · direct use of Symfony\Component\Translation types in userland (blocked by TranslateBoundaryPass and TranslateBoundaryValidator).

This is a capability package. It adds optional translation to a Scafera project. It does not define folder structure or architectural rules — those belong to architecture packages.

What it provides

• Translator — get translated strings with {name} parameter replacement
• LocaleManager — locale switching, available locales, RTL detection
• JsonFileLoader — loads flat JSON translation files (internal)
• Twig integration — {{ t() }} and {{ locale_direction() }} (when scafera/frontend is installed)
• Companion bundle auto-discovery via extra.scafera-bundles in composer.json

Design decisions

• {name} parameter syntax, not %name% — translation files use {name} for parameter placeholders. This is engine-independent (Symfony uses %name%) and human-readable. Replacement is done after Symfony's trans() call via simple strtr().
• Translations directory is architecture-owned — defined by getTranslationsDir() on the architecture package, not hardcoded. For scafera/layered, this is resources/translations/.
• JSON only — no YAML, no XLIFF. Flat key-value format. Keeps translation files simple and parseable by any tooling.
• Companion bundle for Twig — the {{ t() }} function is registered via extra.scafera-bundles companion discovery (ADR-056), not by requiring scafera/frontend as a dependency. The translate package works without Twig.
• Missing keys return the raw key — get('MISSING') returns 'MISSING', not an error. Fallback to default locale is automatic for keys that exist in another locale.

Installation

composer require scafera/translate

Requirements

• PHP >= 8.4
• scafera/kernel

Translation files

JSON files in the architecture-defined translations directory (e.g., resources/translations/{locale}.json):

{
    "WELCOME": "Welcome to the app!",
    "GREETING": "Hello, {name}!"
}

Flat key-value format. No nesting, no YAML, no XLIFF. Parameters use {name} syntax — not Symfony's %name% format. This keeps translation files engine-independent and human-readable.

Usage

use Scafera\Translate\Translator;

$translator->get('WELCOME');                        // 'Welcome to the app!'
$translator->get('GREETING', ['name' => 'Alice']);  // 'Hello, Alice!'
$translator->has('WELCOME');                        // true
$translator->getLocale();                           // 'en'
$translator->getDirection();                        // 'ltr'

Missing keys return the raw key string. Fallback to the default locale is automatic.

Locale management

use Scafera\Translate\LocaleManager;

$localeManager->setLocale('ar');
$localeManager->getLocale();              // 'ar'
$localeManager->getDirection();           // 'rtl'
$localeManager->getDirection('en');       // 'ltr'
$localeManager->getAvailableLocales();    // ['ar', 'en']

Available locales are discovered from *.json files in the translations directory.

Twig integration

When scafera/frontend is installed, a companion bundle registers automatically:

<html dir="{{ locale_direction() }}">
    <h1>{{ t('WELCOME') }}</h1>
    <p>{{ t('GREETING', {name: user.name}) }}</p>
</html>

Configuration

All configuration is optional. The package works out of the box with sensible defaults.

Not configurable via parameters:

• Translation files directory — defined by the architecture package via getTranslationsDir(). For scafera/layered, this is resources/translations/.
• File format — JSON only. No YAML, no XLIFF.
• Fallback chain — always falls back to the default locale. No multi-level fallback.

To override defaults, add to config/config.yaml:

# config/config.yaml
parameters:
    scafera.translate.default_locale: fr
    scafera.translate.rtl_locales: [ar, fa, ur]

If you are using en as your default locale and the standard RTL set, no configuration is needed.

Boundary enforcement

Enforced via compiler pass (build time) and validator (scafera validate). Detects use, new, and extends patterns.

License

MIT