{"record":{"id":"ebbbac7464cf4530","repo":"phalcon/cphalcon","slug":"parameter-locale-is-required","errorCode":null,"errorMessage":"Parameter 'locale' is required","messagePattern":"Parameter 'locale' is required","errorType":"exception","errorClass":"Phalcon\\Translate\\Exceptions\\MissingRequiredParameter","httpStatus":null,"severity":"error","filePath":"phalcon/Translate/Adapter/Gettext.zep","lineNumber":292,"sourceCode":"     * @phpstan-return translate_gettext_defaults\n     */\n    protected function getOptionsDefault() -> array\n    {\n        return [\n            \"category\":      LC_ALL,\n            \"defaultDomain\": \"messages\"\n        ];\n    }\n\n    /**\n     * Validator for constructor\n     *\n     * @phpstan-param translate_gettext_options $options\n     */\n    protected function prepareOptions( array options) -> void\n    {\n        if unlikely !isset options[\"locale\"] {\n            throw new MissingRequiredParameter(\"locale\");\n        }\n\n        if unlikely !isset options[\"directory\"] {\n            throw new MissingRequiredParameter(\"directory\");\n        }\n\n        let options = array_merge(\n            this->getOptionsDefault(),\n            options\n        );\n\n        this->setLocale(options[\"category\"], options[\"locale\"]);\n        this->setDefaultDomain(options[\"defaultDomain\"]);\n        this->setDirectory(options[\"directory\"]);\n        this->setDomain(options[\"defaultDomain\"]);\n    }\n}\n","sourceCodeStart":274,"sourceCodeEnd":310,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Translate/Adapter/Gettext.zep#L274-L310","documentation":"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).","triggerScenarios":"new Gettext($factory, ['directory' => ..., 'defaultDomain' => ...]) without a 'locale' key; locale values computed from negotiation that end up null so the key is never set.","commonSituations":"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).","solutions":["Add 'locale' => 'de_DE.UTF-8' — a locale string actually installed on the system (locale -a).","Derive the locale explicitly (Accept-Language negotiation map) and assert it is a non-empty string before constructing.","Validate required keys (locale, directory) before instantiation when options are assembled dynamically."],"exampleFix":"// before\n$t = new Gettext($factory, ['directory' => '/app/locales']);\n\n// after\n$t = new Gettext($factory, [\n    'locale'    => 'de_DE.UTF-8',\n    'directory' => '/app/locales',\n]);","handlingStrategy":"validation","validationCode":"$options['locale'] = $options['locale'] ?? $localeNegotiator->resolve($request);\nif (empty($options['locale']) || !is_string($options['locale'])) {\n    throw new InvalidArgumentException('Gettext adapter requires a non-empty string locale');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate assembled options with array_diff(['locale', 'directory'], array_keys($options)) before constructing.","Ensure the locale string exists on the system (locale -a) so setlocale does not silently fail later.","Name the option exactly 'locale' — not 'language' or 'lang'."],"tags":["phalcon","translate","gettext","locale","missing-option","i18n"],"backgroundTag":"missing-required-option","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}