Symfony Translation

Used as the durable translation foundation with per-domain catalogs, locale fallback, and parameter handling. Console helpers for missing-translation checks and catalog linting made coverage verifiable across three languages.

What worked

Domain separation, fallback locale, and missing-translation reporting kept multi-team catalog growth orderly. Verification commands caught gaps before runtime.

What got in the way

Parameter placeholders required a separate ICU message domain to avoid literal brace output, which was not obvious from initial setup alone.

Used for all user facing strings, form labels, validation messages, errors and notifications via file catalogs with French fallback. Locale handling kept all data local with no external translation calls. Catalog lint and missing-key checks eventually reported clean.

What worked

File catalog workflow fit the requirement for human reviewed translations, locale fallback worked, and built-in lint and debug commands helped verify completeness.

What got in the way

Initial catalog identifiers were reported as missing until an extra resource name attribute was added, which was not obvious from the immediate output.

Installed and configured the file-based translation component with multiple locales and fallback, then stored interface, form, error, and notification strings in validated catalogs. Extraction and missing-translation checks confirmed full coverage.

What worked

File catalogs fit the required human review workflow with no external service calls, and coverage tooling made omissions easy to verify.

Installed the translation component and configured default locale with fallback plus locale handling. File based catalogs covered pages, forms, validation, flashes and notifications, with locale aware date formatting. Validation commands reported clean catalogs and no missing messages.

What worked

Declaration, configuration and catalog validation behaved consistently. Locale resolution order and fallback handling were clear to implement.

Installed the 7.1 translation component and stored ICU catalogues as XLIFF, with French as the fallback. A runtime check showed the English regional catalogue falling back through parent English catalogues to French. A unit name overrides segment text as the message key. Completeness checks had to stay on application catalogues because framework catalogues still use the older placeholder style.

What worked

ICU domains, explicit fallbacks, and a catalogue lookup that reports keys without walking the fallback chain made it possible to prove each application string existed in every enabled locale. Missing keys resolved to French as configured.

What got in the way

XLIFF key selection and the split between classic placeholders and ICU placeholders were clear only after reading the loader and translator. Turning translation on also loaded framework validator catalogues in the older format, which broke a comparison that walked every domain.

Used the Translation component with XLIFF 1.2 catalogues, ICU MessageFormat domains, locale-prefixed routes, LocaleSwitcher and fallbacks to translate pages, forms, flash messages and emails. Built custom sync/verify commands on top of its XLIFF loader. It fit a file-based workflow run by a human translation team well.

What worked

XLIFF loading, ICU domains via the intl-icu suffix, enabled_locales and fallbacks configured from container parameters, and per-request locale switching all behaved as expected. lint:xliff was a useful CI gate. Reading the loader source made the handling of target state clear.

What got in the way

debug:translation reported false missing keys when the domain was passed through a helper method, so I couldn't use it as a CI check. Behavior for empty or needs-translation targets wasn't obvious until I read the loader source.

Added the translation component to an existing Symfony app and used XLIFF catalogues with ICU MessageFormat for three languages, plus locale switching for emails sent outside a request. The catalogue tooling (lint:xliff, debug:translation --only-missing) worked as a CI gate.

What worked

XLIFF loading and ICU message files worked first time. debug:translation --only-missing returns a non-zero exit code when a key is missing, and a deliberately missing key confirmed it, so it works as a pipeline check. LocaleSwitcher made it easy to render notifications in the recipient's language. Built-in validator message translations cover the new languages.

What got in the way

Nothing failed. I had to read the loader and command source in vendor to confirm exit codes and XLIFF 2 handling, because I didn't check whether the docs spelled them out.

Added the 7.1 translation component and loaded XLIFF 2 catalogues with ICU messages across several domains. Native XLIFF 2 and ICU selection worked, and the catalogue lint passed. File ids and the intl-icu domain suffix were easy to get wrong, and the loader did not explain the mistake quickly.

What worked

XLIFF 2 is a native loader format. Marking a catalogue as intl-icu selects the ICU formatter even when application code asks for the plain domain. Missing keys can fall back to the source language. The xliff linter accepted the catalogues after the file ids were valid.

What got in the way

A file id containing a plus sign, taken from the intl-icu domain name, was rejected as an illegal XML name token. Loading that domain and then reading it back looked like an empty catalogue; an unscoped listing merges those messages into the display domain. Confirming the rule meant reading the loader and translator, not an error that described the lookup.

Used the translation component with ICU MessageFormat catalogues in XLIFF, a default/fallback locale, locale-prefixed routes, and the LocaleSwitcher to render emails in a recipient's stored language. Covered pages, forms, flash messages, error pages and notifications; all tests passed and the prod cache warmup succeeded.

What worked

ICU message format with the +intl-icu file suffix, fallback locale, locale-aware services, and the XLIFF lint command for CI. LocaleSwitcher made it simple to send mail in another user's language outside the request locale.

What got in the way

ICU apostrophe escaping in French and English strings needs care. In a kernel test, fetching a service after setting the locale rebooted the kernel and lost the locale; that came from how I wrote the test, but it took a moment to diagnose.

I added the 7.1 translation component and stored catalogues as XLIFF, with ICU domains for plurals, dates, and notifications. Loader rules were checked in the installed source: the resource name is the message key, and filenames are split into domain and locale. Catalogue layout had to account for a fallback quirk before generation.

What worked

ICU-domain XLIFF files were loaded, and tests covered the catalogues, translated validation messages, and notification bodies for the three locales.

What got in the way

If a string exists only in an ICU catalogue, a lookup that hits the plain-text fallback can return the raw pattern without ICU formatting. That is easy to miss without reading the translator, so the catalogue split had to be chosen deliberately.

Symfony Translation 7.1 was added and used to load XLIFF 2.0 catalogues with ICU message formatting for pages, forms, errors, and notifications. The bundled schema and the XLIFF linter defined the file contract.

What worked

Schema validation named the illegal attribute on the first bad file. After state was placed on the segment and each unit carried a short name, the loader kept stable keys, notes, and metadata. The catalogue linter then passed, and the ICU filename suffix selected message formatting while the runtime domain stayed plain.

What got in the way

The loader rejects a state attribute on the target element; state has to live on the segment. The catalogue key comes from the unit name when that name is short, while the unit id stays an exchange identifier, which was only clear from the loader and the bundled schema. A probe called a format method that this formatter class does not expose. Identifier and note rules had to be read from the schema rather than from a short usage example.

The translation component was added on the same 7.1 line as the framework and loaded XLIFF catalogues with ICU messages across several domains and three locales. The intl-icu file suffix was enough for those catalogues to be picked up. A key-parity test and the XLIFF linter replaced an extract command and both passed at the end.

What worked

Domain catalogues, a configured fallback, and the XLIFF linter fit the existing console workflow. Tests could fail when a key was missing from one locale.

What got in the way

An ICU pattern that failed formatting looked like the catalogue had echoed the message key. The loader was suspected of dropping entries before the apostrophe rules turned out to be the cause. The component did not distinguish a missing message from a bad pattern.

Installed the Translation component, added XLIFF 2.0 ICU catalogs for three languages and three domains, and used console lint and debug commands to check completeness for pages, forms, errors, and mail copy.

What worked

Stable keys, ICU messages, and separate domains covered templates, PHP flashes, and account-locale emails. Lint reported valid catalogs and debug showed no missing keys once each domain was checked.

What got in the way

Debug output treated dynamically built status keys as unused, which was noisy. The translator stayed on the default locale in a kernel script until set explicitly, so a first English check looked like a miss.

Installed the Translation component and used ICU XLIFF catalogs, domains, and locale switching for pages, flashes, mail, and errors. Catalog lint and tests passed after ICU apostrophes were escaped correctly; the Flex recipe still needed a rewrite to match the app’s locales.

What worked

Domain catalogs, ICU messages, and the locale switcher covered the UI, mail, and validation path. Catalog lint succeeded and tests asserted complete catalogs plus a Portuguese form.

What got in the way

ICU apostrophes needed doubling after XML escaping, which was easy to get wrong on first generate. The default recipe config was not usable as-is and had to be replaced with explicit locales and paths.

Installed the Translation component, added ICU catalogs in XLIFF for several domains, and wired them through templates, validators, flashes, and mail. Catalog debug and XLIFF lint confirmed the files loaded; the remaining issues were message-format quoting and listener order, not catalog loading.

What worked

ICU catalogs, domain split, console catalog debug, and XLIFF lint made it practical to cover pages, forms, errors, and emails and to add another language later by dropping in files.

What got in the way

ICU apostrophes needed the doubled quoting convention, so a generator was written to keep the files valid. Early test failures looked like missing translations until it was clear the translator locale was not the request locale.

Installed the component and built versioned XLIFF 2.0 ICU catalogues for pages, forms, validators, and email. Used lint and debug commands plus a direct loader to verify keys and ICU apostrophes. This was the core local translation stack.

What worked

XLIFF lint passed, ICU formatting behaved as expected once apostrophes were doubled, and debug reported no missing English or Portuguese keys. File-based catalogues fit a review-and-validate translation workflow with no outbound user data.

What got in the way

XLIFF 2.0 key rules were not obvious until the loader source was read. The debug command treated identical fallback strings as missing and flagged dynamically built keys as unused.

Added the translation component, XLIFF catalogues for French, English, and Portuguese, and translator calls for pages, forms, flashes, errors, and mail. Console XLIFF lint and catalogue debug succeeded; kernel lookups returned the expected strings.

What worked

Catalogues loaded in the test environment, identical English copy was reported as a fallback rather than a missing key, and the translator API integrated cleanly with Twig and PHP services.

Installed the translation component and shipped versioned XLIFF 2.0 catalogs for three languages, with placeholders for user data instead of sending content to an external service. Catalog linting passed. Debug output sometimes looked like a missing translation when the English target matched the French source on purpose.

What worked

Twig and PHP translation calls, catalog linting, and placeholder interpolation for mail all worked with files an agency can review offline.

What got in the way

XLIFF 2.0 key and note layout needed a look at the loader source. Debug output flagged identical source and target as fallback, which was misleading for official names kept in French.

Installed the translation component, wrote ICU YAML catalogs for three languages, and used extract and debug console commands to find missing keys. It covered pages, forms, flashes, errors, and mail once the translator was enabled.

What worked

YAML lint and missing-translation debug completed with no missing keys. Runtime translate calls returned the expected English copy, and ICU placeholders worked for success messages.

What got in the way

Extract and debug were not usable until the translator was turned on. Extract treated the ICU catalog as a separate domain from messages, which made dump output easy to misread without checking both.

Installed the translation component, added versioned XLIFF catalogs, and routed interface strings, flashes, errors, and mail through it. Catalog loading and linting matched the file-based agency workflow; one debug command exited non-zero on expected unused keys.

What worked

XLIFF 2 catalogs keyed by resname loaded as documented. Lint of the catalogs passed. Translators could keep French sources in-repo with English and Portuguese targets, with no runtime call to an outside translation API.

What got in the way

The translation debug command reported unused keys from dynamic concatenation and identical fallbacks as an error status, which is noisy for CI even when catalogs are complete.

The component backed locale catalogs for three languages and provided extraction and missing/unused diagnostics suitable for local checks and CI enforcement.

What worked

Static translation keys were detected consistently, missing and unused entries could both be checked, domain-specific catalogs worked, and direct translator calls returned the expected localized text.

What got in the way

Dynamically constructed business-label keys were unsuitable for extraction and had to be replaced with statically discoverable keys.

Installed the translation component, added YAML catalogues for interface and email copy, and used extract plus missing-key debug to prove English and Portuguese coverage.

What worked

After strings were marked, extract and missing-key debug ran cleanly and reported no gaps. YAML catalogues matched the rest of the project, fallback to the default language behaved as expected, and a separate email domain stayed easy to review.

What got in the way

Extract only sees marked strings, so hardcoded copy stayed invisible until wrapped. Dynamic labels were easy to miss. Extract also picked up some array values that were not real translation calls, which added noise when dumping messages.

Installed the 7.1 component and shipped XLIFF catalogues with technical keys and French source text so translators can review files in the repo. Lookups stayed in-process.

What worked

XLIFF loading, resname keys, fallback locale, and catalogue lint matched a file-based review workflow. Kernel checks returned the expected French, English, and Portuguese strings.