[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/l10n/ -> class-wp-translation-controller.php (source)

   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  }


Generated : Thu Nov 19 08:20:01 2026 Cross-referenced by PHPXref