PHPOffice/PHPWord · error · InvalidArgumentException

is not a valid language code

Error message

 is not a valid language code

What it means

PhpWord\Style\Language::validateLocale checks that a language/locale code passed to setLatin, setEastAsia or setBidirectional is either null, 'zxx' (no language), 'und' (mapped to en-EN), or of the form xx or xx-YY. A non-null string without a hyphen that is not a known special code throws InvalidArgumentException saying it is not a valid language code.

Solutions

1. Pass an ISO 639-1 two-letter code, optionally with region: 'en', 'de', 'en-US'
2. Use 'zxx' for 'no language' and 'und' for undetermined instead of other placeholders
3. Validate input with preg_match('/^[a-z]{2}(-[A-Z]{2})?$/') before setting

Example fix

// before
$language = new Language(['latin' => 'english']);
// after
$language = new Language(['latin' => 'en-US']);

function isValidLocale(?string $locale): bool {
    return $locale === null || in_array($locale, ['zxx','und'], true)
        || preg_match('/^[a-zA-Z]{2}(-[a-zA-Z]{2})?$/', $locale) === 1;
}
// use: if (!isValidLocale($lang)) { $lang = 'en-US'; }

function normalizeLocale(?string $locale): ?string {
    if ($locale === null || in_array($locale, ['zxx','und'], true)) return $locale;
    return preg_match('/^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})?$/', $locale) === 1 ? $locale : 'en-US';
}

try {
    $language->setLatin($locale);
} catch (\InvalidArgumentException $e) {
    $language->setLatin('en-US'); // safe fallback
}

When it happens

Trigger: Constructing a Language style with values like Language::setLatin('english') or a bare made-up code ('foo') instead of an ISO 639 code such as 'en' or 'en-US'.

Common situations: Passing a human-readable language name ('German', 'english') instead of an ISO code; passing a 3-letter code not in the expected form; internationalization code copied from a different locale framework.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid image
• salt has to be of exactly 16 bytes length
• Type must be "start" or "end"
• Invalid style value: Options
• Line height must be a valid number

AI-assisted analysis of PHPOffice/PHPWord@aef95c0415 (2026-09-14). Data as JSON: /api/errors/3294ff31c6685819. Report an issue: GitHub.

Appendix: source

Thrown at src/PhpWord/Style/Language.php:256

     *
     * @param string $locale
     *
     * @return string
     */
    private function validateLocale($locale)
    {
        if ($locale !== null) {
            $locale = str_replace('_', '-', $locale);
        }

        if ($locale !== null && strlen($locale) === 2) {
            return strtolower($locale) . '-' . strtoupper($locale);
        }
        if ($locale === 'und') {
            return 'en-EN';
        }
        if ($locale !== null && $locale !== 'zxx' && strstr($locale, '-') === false) {
            throw new InvalidArgumentException($locale . ' is not a valid language code');
        }

        return $locale;
    }
}

View on GitHub (pinned to aef95c0415)