symfony/translation · error · RuntimeException

Loading translations from the QT format requires the…

Error message

Loading translations from the QT format requires the Symfony Config component.

What it means

QtFileLoader parses QT translation TS (XML) files using Symfony's XmlUtils. That class lives in the symfony/config component; when it is not installed the loader cannot work and throws RuntimeException instead of a cryptic class-not-found error.

Solutions

Run `composer require symfony/config` to install the missing component.
Alternatively convert QT .ts files to XLIFF/PO and use a loader with no extra dependency.
Pin a symfony/config version compatible with your symfony/translation version after installing.
Verify with `php -r 'var_dump(class_exists("Symfony\\Component\\Config\\Util\\XmlUtils"));'` before deploying.

Example fix

// before
composer require symfony/translation  // config component missing
// after
composer require symfony/translation symfony/config

Defensive patterns

Strategy: fallback

Validate before calling

if (!class_exists(\Symfony\Component\Config\Util\XmlUtils::class)) {
    throw new \RuntimeException('QT loading needs symfony/config; run composer require symfony/config');
}

Try / catch

try {
    $catalogue = $qtLoader->load($file, $locale);
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'Config component')) {
        $catalogue = $xliffLoader->load(convertedFile, $locale); // pre-converted fallback
    } else {
        throw $e;
    }
}

Prevention

Require symfony/config explicitly in composer.json if QT loading is used
Run class_exists checks in your translation bootstrap
Prefer XLIFF/PO formats to avoid optional dependencies
Add a composer platform/dependency test in CI

When it happens

Trigger: Calling QtFileLoader::load() in a project where symfony/config is not installed (it is a suggested, not required, dependency of symfony/translation).

Common situations: Minimal installs with only symfony/translation, projects that removed symfony/config as transitive dependency, composer installs with --no-suggest that never added the optional package.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of symfony/translation@ae9e8a51bc (2026-09-15). Data as JSON: /api/errors/2f2e48f2f45a27e0. Report an issue: GitHub.

Appendix: source

Thrown at Loader/QtFileLoader.php:31

use Symfony\Component\Config\Resource\FileResource;
use Symfony\Component\Config\Util\XmlUtils;
use Symfony\Component\Translation\Exception\InvalidResourceException;
use Symfony\Component\Translation\Exception\NotFoundResourceException;
use Symfony\Component\Translation\Exception\RuntimeException;
use Symfony\Component\Translation\MessageCatalogue;

/**
 * QtFileLoader loads translations from QT Translations XML files.
 *
 * @author Benjamin Eberlei <kontakt@beberlei.de>
 */
class QtFileLoader implements LoaderInterface
{
    public function load(mixed $resource, string $locale, string $domain = 'messages'): MessageCatalogue
    {
        if (!class_exists(XmlUtils::class)) {
            throw new RuntimeException('Loading translations from the QT format requires the Symfony Config component.');
        }

        if (!stream_is_local($resource)) {
            throw new InvalidResourceException(\sprintf('This is not a local file "%s".', $resource));
        }

        if (!file_exists($resource)) {
            throw new NotFoundResourceException(\sprintf('File "%s" not found.', $resource));
        }

        try {
            $dom = XmlUtils::loadFile($resource);
        } catch (\InvalidArgumentException $e) {
            throw new InvalidResourceException(\sprintf('Unable to load "%s".', $resource), $e->getCode(), $e);
        }

        $internalErrors = libxml_use_internal_errors(true);
        libxml_clear_errors();

View on GitHub (pinned to ae9e8a51bc)