phalcon/cphalcon · error · Phalcon\Translate\Exceptions\MissingRequiredParameter

Parameter 'locale' is required

Error message

Parameter 'locale' is required

What it means

Gettext::prepareOptions() validates the constructor options in a fixed order; the 'locale' option (a setlocale()-style string like 'de_DE.UTF-8') is mandatory and its absence throws Phalcon\Translate\Exceptions\MissingRequiredParameter('locale') during construction (phalcon/Translate/Adapter/Gettext.zep:292).

Source

Thrown at phalcon/Translate/Adapter/Gettext.zep:292

     * @phpstan-return translate_gettext_defaults
     */
    protected function getOptionsDefault() -> array
    {
        return [
            "category":      LC_ALL,
            "defaultDomain": "messages"
        ];
    }

    /**
     * Validator for constructor
     *
     * @phpstan-param translate_gettext_options $options
     */
    protected function prepareOptions( array options) -> void
    {
        if unlikely !isset options["locale"] {
            throw new MissingRequiredParameter("locale");
        }

        if unlikely !isset options["directory"] {
            throw new MissingRequiredParameter("directory");
        }

        let options = array_merge(
            this->getOptionsDefault(),
            options
        );

        this->setLocale(options["category"], options["locale"]);
        this->setDefaultDomain(options["defaultDomain"]);
        this->setDirectory(options["directory"]);
        this->setDomain(options["defaultDomain"]);
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add 'locale' => 'de_DE.UTF-8' — a locale string actually installed on the system (locale -a).
2. Derive the locale explicitly (Accept-Language negotiation map) and assert it is a non-empty string before constructing.
3. Validate required keys (locale, directory) before instantiation when options are assembled dynamically.

Example fix

// before
$t = new Gettext($factory, ['directory' => '/app/locales']);

// after
$t = new Gettext($factory, [
    'locale'    => 'de_DE.UTF-8',
    'directory' => '/app/locales',
]);

$options['locale'] = $options['locale'] ?? $localeNegotiator->resolve($request);
if (empty($options['locale']) || !is_string($options['locale'])) {
    throw new InvalidArgumentException('Gettext adapter requires a non-empty string locale');
}

When it happens

Trigger: new Gettext($factory, ['directory' => ..., 'defaultDomain' => ...]) without a 'locale' key; locale values computed from negotiation that end up null so the key is never set.

Common situations: Naming the option 'language' or 'lang' instead of 'locale'; locale derived from session/headers returning null after a refactor; config files that omit locale in one environment (e.g. CLI bootstrap vs web bootstrap).

Related errors

• Parameter 'directory' is required
• Parameter 'content' is required
• This class requires the gettext extension for PHP
• Translation content was not provided
• Cannot find translation key: {key}

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/ebbbac7464cf4530. Report an issue: GitHub.