| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * I18N: WP_Translation_Controller class. 4 * 5 * @package WordPress 6 * @subpackage I18N 7 * @since 6.5.0 8 */ 9 10 /** 11 * Class WP_Translation_Controller. 12 * 13 * @since 6.5.0 14 */ 15 final class WP_Translation_Controller { 16 /** 17 * Current locale. 18 * 19 * @since 6.5.0 20 * @var string 21 */ 22 protected $current_locale = 'en_US'; 23 24 /** 25 * Map of loaded translations per locale and text domain. 26 * 27 * [ Locale => [ Textdomain => [ ..., ... ] ] ] 28 * 29 * @since 6.5.0 30 * @var array<string, array<string, WP_Translation_File[]>> 31 */ 32 protected $loaded_translations = array(); 33 34 /** 35 * List of loaded translation files. 36 * 37 * [ Filename => [ Locale => [ Textdomain => WP_Translation_File ] ] ] 38 * 39 * @since 6.5.0 40 * @var array<string, array<string, array<string, WP_Translation_File|false>>> 41 */ 42 protected $loaded_files = array(); 43 44 /** 45 * Container for the main instance of the class. 46 * 47 * @since 6.5.0 48 * @var WP_Translation_Controller|null 49 */ 50 private static $instance = null; 51 52 /** 53 * Utility method to retrieve the main instance of the class. 54 * 55 * The instance will be created if it does not exist yet. 56 * 57 * @since 6.5.0 58 * 59 * @return WP_Translation_Controller 60 */ 61 public static function get_instance(): WP_Translation_Controller { 62 self::$instance ??= new self(); 63 64 return self::$instance; 65 } 66 67 /** 68 * Returns the current locale. 69 * 70 * @since 6.5.0 71 * 72 * @return string Locale. 73 */ 74 public function get_locale(): string { 75 return $this->current_locale; 76 } 77 78 /** 79 * Sets the current locale. 80 * 81 * @since 6.5.0 82 * 83 * @param string $locale Locale. 84 */ 85 public function set_locale( string $locale ) { 86 $this->current_locale = $locale; 87 } 88 89 /** 90 * Loads a translation file for a given text domain. 91 * 92 * @since 6.5.0 93 * 94 * @param string $translation_file Translation file. 95 * @param string $textdomain Optional. Text domain. Default 'default'. 96 * @param string $locale Optional. Locale. Default current locale. 97 * @return bool True on success, false otherwise. 98 */ 99 public function load_file( string $translation_file, string $textdomain = 'default', ?string $locale = null ): bool { 100 $locale ??= $this->current_locale; 101 102 $translation_file = realpath( $translation_file ); 103 104 if ( false === $translation_file ) { 105 return false; 106 } 107 108 if ( 109 isset( $this->loaded_files[ $translation_file ][ $locale ][ $textdomain ] ) && 110 false !== $this->loaded_files[ $translation_file ][ $locale ][ $textdomain ] 111 ) { 112 return null === $this->loaded_files[ $translation_file ][ $locale ][ $textdomain ]->error(); 113 } 114 115 if ( 116 isset( $this->loaded_files[ $translation_file ][ $locale ] ) && 117 array() !== $this->loaded_files[ $translation_file ][ $locale ] 118 ) { 119 $moe = reset( $this->loaded_files[ $translation_file ][ $locale ] ); 120 } else { 121 $moe = WP_Translation_File::create( $translation_file ); 122 if ( false === $moe || null !== $moe->error() ) { 123 $moe = false; 124 } 125 } 126 127 $this->loaded_files[ $translation_file ][ $locale ][ $textdomain ] = $moe; 128 129 if ( ! $moe instanceof WP_Translation_File ) { 130 return false; 131 } 132 133 $this->loaded_translations[ $locale ][ $textdomain ] ??= array(); 134 135 $this->loaded_translations[ $locale ][ $textdomain ][] = $moe; 136 137 return true; 138 } 139 140 /** 141 * Unloads a translation file for a given text domain. 142 * 143 * @since 6.5.0 144 * 145 * @param WP_Translation_File|string $file Translation file instance or file name. 146 * @param string $textdomain Optional. Text domain. Default 'default'. 147 * @param string $locale Optional. Locale. Defaults to all locales. 148 * @return bool True on success, false otherwise. 149 */ 150 public function unload_file( $file, string $textdomain = 'default', ?string $locale = null ): bool { 151 if ( is_string( $file ) ) { 152 $file = realpath( $file ); 153 } 154 155 if ( null !== $locale ) { 156 if ( isset( $this->loaded_translations[ $locale ][ $textdomain ] ) ) { 157 foreach ( $this->loaded_translations[ $locale ][ $textdomain ] as $i => $moe ) { 158 if ( $file === $moe || $file === $moe->get_file() ) { 159 unset( $this->loaded_translations[ $locale ][ $textdomain ][ $i ] ); 160 unset( $this->loaded_files[ $moe->get_file() ][ $locale ][ $textdomain ] ); 161 return true; 162 } 163 } 164 } 165 166 return true; 167 } 168 169 foreach ( $this->loaded_translations as $l => $domains ) { 170 if ( ! isset( $domains[ $textdomain ] ) ) { 171 continue; 172 } 173 174 foreach ( $domains[ $textdomain ] as $i => $moe ) { 175 if ( $file === $moe || $file === $moe->get_file() ) { 176 unset( $this->loaded_translations[ $l ][ $textdomain ][ $i ] ); 177 unset( $this->loaded_files[ $moe->get_file() ][ $l ][ $textdomain ] ); 178 return true; 179 } 180 } 181 } 182 183 return false; 184 } 185 186 /** 187 * Unloads all translation files for a given text domain. 188 * 189 * @since 6.5.0 190 * 191 * @param string $textdomain Optional. Text domain. Default 'default'. 192 * @param string $locale Optional. Locale. Defaults to all locales. 193 * @return bool True on success, false otherwise. 194 */ 195 public function unload_textdomain( string $textdomain = 'default', ?string $locale = null ): bool { 196 $unloaded = false; 197 198 if ( null !== $locale ) { 199 if ( isset( $this->loaded_translations[ $locale ][ $textdomain ] ) ) { 200 $unloaded = true; 201 foreach ( $this->loaded_translations[ $locale ][ $textdomain ] as $moe ) { 202 unset( $this->loaded_files[ $moe->get_file() ][ $locale ][ $textdomain ] ); 203 } 204 } 205 206 unset( $this->loaded_translations[ $locale ][ $textdomain ] ); 207 208 return $unloaded; 209 } 210 211 foreach ( $this->loaded_translations as $l => $domains ) { 212 if ( ! isset( $domains[ $textdomain ] ) ) { 213 continue; 214 } 215 216 $unloaded = true; 217 218 foreach ( $domains[ $textdomain ] as $moe ) { 219 unset( $this->loaded_files[ $moe->get_file() ][ $l ][ $textdomain ] ); 220 } 221 222 unset( $this->loaded_translations[ $l ][ $textdomain ] ); 223 } 224 225 return $unloaded; 226 } 227 228 /** 229 * Determines whether translations are loaded for a given text domain. 230 * 231 * @since 6.5.0 232 * 233 * @param string $textdomain Optional. Text domain. Default 'default'. 234 * @param string $locale Optional. Locale. Default current locale. 235 * @return bool True if there are any loaded translations, false otherwise. 236 */ 237 public function is_textdomain_loaded( string $textdomain = 'default', ?string $locale = null ): bool { 238 $locale ??= $this->current_locale; 239 240 return isset( $this->loaded_translations[ $locale ][ $textdomain ] ) && 241 array() !== $this->loaded_translations[ $locale ][ $textdomain ]; 242 } 243 244 /** 245 * Translates a singular string. 246 * 247 * @since 6.5.0 248 * 249 * @param string $text Text to translate. 250 * @param string $context Optional. Context for the string. Default empty string. 251 * @param string $textdomain Optional. Text domain. Default 'default'. 252 * @param string $locale Optional. Locale. Default current locale. 253 * @return string|false Translation on success, false otherwise. 254 */ 255 public function translate( string $text, string $context = '', string $textdomain = 'default', ?string $locale = null ) { 256 if ( '' !== $context ) { 257 $context .= "\4"; 258 } 259 260 $translation = $this->locate_translation( "{$context}{$text}", $textdomain, $locale ); 261 262 if ( false === $translation ) { 263 return false; 264 } 265 266 return $translation['entries'][0]; 267 } 268 269 /** 270 * Translates plurals. 271 * 272 * Checks both singular+plural combinations as well as just singulars, 273 * in case the translation file does not store the plural. 274 * 275 * @since 6.5.0 276 * 277 * @param array $plurals { 278 * Pair of singular and plural translations. 279 * 280 * @type string $0 Singular translation. 281 * @type string $1 Plural translation. 282 * } 283 * @param int $number Number of items. 284 * @param string $context Optional. Context for the string. Default empty string. 285 * @param string $textdomain Optional. Text domain. Default 'default'. 286 * @param string|null $locale Optional. Locale. Default current locale. 287 * @return string|false Translation on success, false otherwise. 288 */ 289 public function translate_plural( array $plurals, int $number, string $context = '', string $textdomain = 'default', ?string $locale = null ) { 290 if ( '' !== $context ) { 291 $context .= "\4"; 292 } 293 294 $text = implode( "\0", $plurals ); 295 $translation = $this->locate_translation( "{$context}{$text}", $textdomain, $locale ); 296 297 if ( false === $translation ) { 298 $text = $plurals[0]; 299 $translation = $this->locate_translation( "{$context}{$text}", $textdomain, $locale ); 300 301 if ( false === $translation ) { 302 return false; 303 } 304 } 305 306 /** @var WP_Translation_File $source */ 307 $source = $translation['source']; 308 $num = $source->get_plural_form( $number ); 309 310 // See \Translations::translate_plural(). 311 return $translation['entries'][ $num ] ?? $translation['entries'][0]; 312 } 313 314 /** 315 * Returns all existing headers for a given text domain. 316 * 317 * @since 6.5.0 318 * 319 * @param string $textdomain Optional. Text domain. Default 'default'. 320 * @return array<string, string> Headers. 321 */ 322 public function get_headers( string $textdomain = 'default' ): array { 323 if ( array() === $this->loaded_translations ) { 324 return array(); 325 } 326 327 $headers = array(); 328 329 foreach ( $this->get_files( $textdomain ) as $moe ) { 330 foreach ( $moe->headers() as $header => $value ) { 331 $headers[ $this->normalize_header( $header ) ] = $value; 332 } 333 } 334 335 return $headers; 336 } 337 338 /** 339 * Normalizes header names to be capitalized. 340 * 341 * @since 6.5.0 342 * 343 * @param string $header Header name. 344 * @return string Normalized header name. 345 */ 346 protected function normalize_header( string $header ): string { 347 $parts = explode( '-', $header ); 348 $parts = array_map( 'ucfirst', $parts ); 349 return implode( '-', $parts ); 350 } 351 352 /** 353 * Returns all entries for a given text domain. 354 * 355 * @since 6.5.0 356 * 357 * @param string $textdomain Optional. Text domain. Default 'default'. 358 * @return array<string, string> Entries. 359 */ 360 public function get_entries( string $textdomain = 'default' ): array { 361 if ( array() === $this->loaded_translations ) { 362 return array(); 363 } 364 365 $entries = array(); 366 367 foreach ( $this->get_files( $textdomain ) as $moe ) { 368 $entries = array_merge( $entries, $moe->entries() ); 369 } 370 371 return $entries; 372 } 373 374 /** 375 * Locates translation for a given string and text domain. 376 * 377 * @since 6.5.0 378 * 379 * @param string $singular Singular translation. 380 * @param string $textdomain Optional. Text domain. Default 'default'. 381 * @param string $locale Optional. Locale. Default current locale. 382 * @return array{source: WP_Translation_File, entries: string[]}|false { 383 * Translations on success, false otherwise. 384 * 385 * @type WP_Translation_File $source Translation file instance. 386 * @type string[] $entries Array of translation entries. 387 * } 388 */ 389 protected function locate_translation( string $singular, string $textdomain = 'default', ?string $locale = null ) { 390 if ( array() === $this->loaded_translations ) { 391 return false; 392 } 393 394 // Find the translation in all loaded files for this text domain. 395 foreach ( $this->get_files( $textdomain, $locale ) as $moe ) { 396 $translation = $moe->translate( $singular ); 397 if ( false !== $translation ) { 398 return array( 399 'entries' => explode( "\0", $translation ), 400 'source' => $moe, 401 ); 402 } 403 if ( null !== $moe->error() ) { 404 // Unload this file, something is wrong. 405 $this->unload_file( $moe, $textdomain, $locale ); 406 } 407 } 408 409 // Nothing could be found. 410 return false; 411 } 412 413 /** 414 * Returns all translation files for a given text domain. 415 * 416 * @since 6.5.0 417 * 418 * @param string $textdomain Optional. Text domain. Default 'default'. 419 * @param string $locale Optional. Locale. Default current locale. 420 * @return WP_Translation_File[] List of translation files. 421 */ 422 protected function get_files( string $textdomain = 'default', ?string $locale = null ): array { 423 $locale ??= $this->current_locale; 424 425 return $this->loaded_translations[ $locale ][ $textdomain ] ?? array(); 426 } 427 428 /** 429 * Returns a boolean to indicate whether a translation exists for a given string with optional text domain and locale. 430 * 431 * @since 6.7.0 432 * 433 * @param string $singular Singular translation to check. 434 * @param string $textdomain Optional. Text domain. Default 'default'. 435 * @param ?string $locale Optional. Locale. Default current locale. 436 * @return bool True if the translation exists, false otherwise. 437 */ 438 public function has_translation( string $singular, string $textdomain = 'default', ?string $locale = null ): bool { 439 $locale ??= $this->current_locale; 440 441 return false !== $this->locate_translation( $singular, $textdomain, $locale ); 442 } 443 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Thu Nov 19 08:20:01 2026 | Cross-referenced by PHPXref |