Ui Translations Laravel Package

Getting Started

First, a reality check. This is not a Laravel package. sylius/ui-translations is a read-only subtree split of the Sylius monorepo — it ships YAML translation catalogs (labels, buttons, form fields, flash messages) for the Sylius admin and shop UI. There is no service provider, no composer.json you want to pull into a Laravel app, no php artisan vendor:publish. If you are on a Laravel codebase, treat this as a reference corpus of UI strings, not a dependency. If you are on Sylius/Symfony, it is already installed as part of sylius/sylius.

Where to look first:

1. src/Resources/translations/ — the actual catalogs, one file per locale (messages.en.yaml, messages.de.yaml, …). This is 95% of the value.
2. composer.json — note the branch-alias and Sylius/Symfony constraints. This tells you which platform version the split corresponds to.
3. The upstream Sylius/Sylius monorepo — the real source of truth, issue tracker, and PR target.

Minimal steps (Sylius app):

# Already present via the platform — just verify:
ls vendor/sylius/sylius/src/Sylius/Bundle/UiBundle/Resources/translations/
bin/console debug:translation en --domain=messages

Minimal steps (Laravel app, reference-only use):

git clone https://github.com/Sylius/UiTranslations /tmp/ui-translations
# Inspect the YAML catalogs for terminology and key naming conventions
# Port selected strings into lang/{locale}/admin.php or resources/lang/*.json

First use case: Pick your target locale, open messages.{locale}.yaml, and confirm it covers the admin flows you care about (orders, catalog, promotions, customers). That file is your baseline; anything missing becomes an override in your own app.

Implementation Patterns

Pattern 1 — Consume via the platform, not directly. Do not composer require sylius/ui-translations. It is versioned in lockstep with sylius/sylius; requiring it separately creates constraint conflicts on every upgrade. Upgrades arrive by bumping Sylius.

Pattern 2 — Override at the application layer. Symfony's translator resolves app-level catalogs before bundle catalogs. The idiomatic override:

# translations/messages.en.yaml  (project root, wins over bundle)
sylius:
  ui:
    order: "Purchase Order"   # override any shipped key

Or, for locale-specific terminology, add translations/messages.de.yaml in your app. This is the only sane customization path — the upstream is READ-ONLY.

Pattern 3 — Key-set diffing as a CI gate. Because coverage is uneven by locale, treat translation completeness as a build artifact:

# pseudocode: compare key sets across locale files
for f in translations/messages.*.yaml; do
  yq 'paths(scalars) | join(".")' "$f" | sort > "/tmp/keys.$(basename $f).txt"
done
comm -23 /tmp/keys.en.txt /tmp/keys.de.txt  # keys missing in de

Fail the build (or warn) when a required locale drops below a coverage threshold. This is how you convert "is it localized?" into a measurable gate.

Pattern 4 — Vendor-fork only when you must patch. If you need a string fix that cannot be overridden (e.g. a key removed upstream), fork into a private VCS namespace, pin the Sylius/Symfony matrix, and patch. Budget the fork maintenance — it is real. For most teams, Pattern 2 is cheaper.

Pattern 5 — Borrow for non-Sylius stacks. On Laravel, the practical move is: dump the catalogs, normalize YAML → PHP arrays, and use the key structure (sylius.ui.*) as a naming convention. You inherit a large, coherent string vocabulary for free under MIT.

Pattern 6 — Terminology glossary as a first-class file. Keep a glossary.yaml in your app mapping canonical domain terms per locale, and validate the shipped catalogs against it in CI. This catches drift after Sylius upgrades without blocking on upstream.

Gotchas and Tips

• READ-ONLY is literal. PRs and issues belong in the Sylius monorepo. Anything you submit here is lost.
• Not a Laravel package — do not try. No service provider, no facades, no Blade. Forcing it into Laravel means a custom YAML loader and translation layer on top of __(), which defeats the purpose.
• Zero stars / zero dependents is not a quality signal, it's a packaging signal. It's a split repo. The real adoption lives with Sylius. But it also means no independent issue queue, no release cadence, no community vetting — you are on Sylius's schedule.
• Do not composer require sylius/ui-translations directly. Constraint conflicts on Sylius/Symfony majors are the #1 way to brick an upgrade.
• Translation cache in Symfony. After editing override files, bin/console cache:clear locally; in prod, the warmup step in deploy must run. Stale catalogs are a silent failure mode.
• Missing keys fail silently. Symfoy falls back to the key string (sylius.ui.foo_bar shows raw in the UI). Use bin/console debug:translation {locale} --domain=messages to see what resolves and what doesn't before you ship.
• Locale file suffixes matter. Files named messages+intl-icu.{locale}.yaml use ICU MessageFormat; plain files use the legacy | plural syntax. Mixing them causes plural rendering bugs. Check which convention your override target uses.
• Override precedence is per-domain and per-locale, not per-key. An app-level messages.en.yaml wins over the bundle's entire file for that domain/locale. If you only meant to override one key, you're now responsible for maintaining the rest — copy the full file, or use a distinct domain.
• RTL is not solved by translations. Locale coverage does not imply layout correctness. Arabic/Hebrew need separate CSS and a QA pass; this package does nothing for that.
• Pluralization and formatting are locale-specific. Symfony's Intl handles most cases, but verify currency, date, and plural edge cases per locale before a launch gate.
• Upgrade-time audit is mandatory. After every Sylius bump, diff the shipped catalogs against your overrides. Keys get renamed and removed; your overrides will silently orphan. Snapshot key sets in CI.
• Data drift between files and any DB-backed translation edits. If you adopt a sylius/ui-translations-style admin CRUD on top of catalogs, decide the source of truth (VCS or DB) before you let an editor touch it. Divergence is painful to reconcile later.
• Extension point you actually want: your app's translations/ directory and the Symfony translator load order. That's it. Everything else is either upstream or a fork.