I18N: Improve PHPStan types for the localization API.

Translatable strings, contexts, and text domains are extracted statically from source, so the gettext functions now require literal strings for these arguments. This lets PHPStan flag values that can never be translated, even when they reach the function indirectly through a variable or a nooped plural array. The return type of these functions remains `string`, since an empty string can still result from the `gettext` filters or from an empty translation in a translation file.

Correcting the documented types of the `$l10n` and `$l10n_unloaded` globals revealed that the return type of `get_translations_for_domain()` has been inaccurate since r57337, because `WP_Translations` does not extend `Translations`. The `$l10n` type retains `MO` since plugins may still assign such instances to the global directly, which `load_textdomain()` accounts for.

Making the declared header shapes hold for `wp_get_pomo_file_data()` and `wp_get_l10n_php_file_data()` required small runtime changes: the former no longer relies on `preg_replace()`, which may return `null`, and the latter now ignores non-string header values from a malformed translation file.

Developed in #14079.
Follow-up to r25520, r38198, r55279, r57337, r58061.

Props westonruter, swissspidy.
See #65817.


git-svn-id: https://develop.svn.wordpress.org/trunk@64232 602fd350-edb4-49c9-b593-d223f7449a82

Author: westonruter

src/wp-includes/class-wp-locale.php

@@ -442,6 +442,8 @@ public function get_list_item_separator() {
 	 *
 	 * @return string Localized word count type. Possible values are `characters_excluding_spaces`,
 	 *                `characters_including_spaces`, or `words`. Defaults to `words`.
+	 *
+	 * @phpstan-return 'characters_excluding_spaces'|'characters_including_spaces'|'words'
 	 */
 	public function get_word_count_type() {