mirror of
https://github.com/WordPress/WordPress.git
synced 2024-10-30 15:31:04 +01:00
56eb5c22d8
A new `has_translation()` function can be used to determine whether a translation exists for a given string. Props louiswol94, swissspidy, drzraf, ckanitz, tomhine, mchirag2002, samuelsilvapt. Fixes #52696. Built from https://develop.svn.wordpress.org/trunk@59029 git-svn-id: http://core.svn.wordpress.org/trunk@58425 1a063a9b-81f0-0310-95a4-ce76da25c4cd
456 lines
13 KiB
PHP
456 lines
13 KiB
PHP
<?php
|
|
/**
|
|
* I18N: WP_Translation_Controller class.
|
|
*
|
|
* @package WordPress
|
|
* @subpackage I18N
|
|
* @since 6.5.0
|
|
*/
|
|
|
|
/**
|
|
* Class WP_Translation_Controller.
|
|
*
|
|
* @since 6.5.0
|
|
*/
|
|
final class WP_Translation_Controller {
|
|
/**
|
|
* Current locale.
|
|
*
|
|
* @since 6.5.0
|
|
* @var string
|
|
*/
|
|
protected $current_locale = 'en_US';
|
|
|
|
/**
|
|
* Map of loaded translations per locale and text domain.
|
|
*
|
|
* [ Locale => [ Textdomain => [ ..., ... ] ] ]
|
|
*
|
|
* @since 6.5.0
|
|
* @var array<string, array<string, WP_Translation_File[]>>
|
|
*/
|
|
protected $loaded_translations = array();
|
|
|
|
/**
|
|
* List of loaded translation files.
|
|
*
|
|
* [ Filename => [ Locale => [ Textdomain => WP_Translation_File ] ] ]
|
|
*
|
|
* @since 6.5.0
|
|
* @var array<string, array<string, array<string, WP_Translation_File|false>>>
|
|
*/
|
|
protected $loaded_files = array();
|
|
|
|
/**
|
|
* Container for the main instance of the class.
|
|
*
|
|
* @since 6.5.0
|
|
* @var WP_Translation_Controller|null
|
|
*/
|
|
private static $instance = null;
|
|
|
|
/**
|
|
* Utility method to retrieve the main instance of the class.
|
|
*
|
|
* The instance will be created if it does not exist yet.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @return WP_Translation_Controller
|
|
*/
|
|
public static function get_instance(): WP_Translation_Controller {
|
|
if ( null === self::$instance ) {
|
|
self::$instance = new self();
|
|
}
|
|
|
|
return self::$instance;
|
|
}
|
|
|
|
/**
|
|
* Returns the current locale.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @return string Locale.
|
|
*/
|
|
public function get_locale(): string {
|
|
return $this->current_locale;
|
|
}
|
|
|
|
/**
|
|
* Sets the current locale.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param string $locale Locale.
|
|
*/
|
|
public function set_locale( string $locale ) {
|
|
$this->current_locale = $locale;
|
|
}
|
|
|
|
/**
|
|
* Loads a translation file for a given text domain.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param string $translation_file Translation file.
|
|
* @param string $textdomain Optional. Text domain. Default 'default'.
|
|
* @param string $locale Optional. Locale. Default current locale.
|
|
* @return bool True on success, false otherwise.
|
|
*/
|
|
public function load_file( string $translation_file, string $textdomain = 'default', ?string $locale = null ): bool {
|
|
if ( null === $locale ) {
|
|
$locale = $this->current_locale;
|
|
}
|
|
|
|
$translation_file = realpath( $translation_file );
|
|
|
|
if ( false === $translation_file ) {
|
|
return false;
|
|
}
|
|
|
|
if (
|
|
isset( $this->loaded_files[ $translation_file ][ $locale ][ $textdomain ] ) &&
|
|
false !== $this->loaded_files[ $translation_file ][ $locale ][ $textdomain ]
|
|
) {
|
|
return null === $this->loaded_files[ $translation_file ][ $locale ][ $textdomain ]->error();
|
|
}
|
|
|
|
if (
|
|
isset( $this->loaded_files[ $translation_file ][ $locale ] ) &&
|
|
array() !== $this->loaded_files[ $translation_file ][ $locale ]
|
|
) {
|
|
$moe = reset( $this->loaded_files[ $translation_file ][ $locale ] );
|
|
} else {
|
|
$moe = WP_Translation_File::create( $translation_file );
|
|
if ( false === $moe || null !== $moe->error() ) {
|
|
$moe = false;
|
|
}
|
|
}
|
|
|
|
$this->loaded_files[ $translation_file ][ $locale ][ $textdomain ] = $moe;
|
|
|
|
if ( ! $moe instanceof WP_Translation_File ) {
|
|
return false;
|
|
}
|
|
|
|
if ( ! isset( $this->loaded_translations[ $locale ][ $textdomain ] ) ) {
|
|
$this->loaded_translations[ $locale ][ $textdomain ] = array();
|
|
}
|
|
|
|
$this->loaded_translations[ $locale ][ $textdomain ][] = $moe;
|
|
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* Unloads a translation file for a given text domain.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param WP_Translation_File|string $file Translation file instance or file name.
|
|
* @param string $textdomain Optional. Text domain. Default 'default'.
|
|
* @param string $locale Optional. Locale. Defaults to all locales.
|
|
* @return bool True on success, false otherwise.
|
|
*/
|
|
public function unload_file( $file, string $textdomain = 'default', ?string $locale = null ): bool {
|
|
if ( is_string( $file ) ) {
|
|
$file = realpath( $file );
|
|
}
|
|
|
|
if ( null !== $locale ) {
|
|
if ( isset( $this->loaded_translations[ $locale ][ $textdomain ] ) ) {
|
|
foreach ( $this->loaded_translations[ $locale ][ $textdomain ] as $i => $moe ) {
|
|
if ( $file === $moe || $file === $moe->get_file() ) {
|
|
unset( $this->loaded_translations[ $locale ][ $textdomain ][ $i ] );
|
|
unset( $this->loaded_files[ $moe->get_file() ][ $locale ][ $textdomain ] );
|
|
return true;
|
|
}
|
|
}
|
|
}
|
|
|
|
return true;
|
|
}
|
|
|
|
foreach ( $this->loaded_translations as $l => $domains ) {
|
|
if ( ! isset( $domains[ $textdomain ] ) ) {
|
|
continue;
|
|
}
|
|
|
|
foreach ( $domains[ $textdomain ] as $i => $moe ) {
|
|
if ( $file === $moe || $file === $moe->get_file() ) {
|
|
unset( $this->loaded_translations[ $l ][ $textdomain ][ $i ] );
|
|
unset( $this->loaded_files[ $moe->get_file() ][ $l ][ $textdomain ] );
|
|
return true;
|
|
}
|
|
}
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Unloads all translation files for a given text domain.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param string $textdomain Optional. Text domain. Default 'default'.
|
|
* @param string $locale Optional. Locale. Defaults to all locales.
|
|
* @return bool True on success, false otherwise.
|
|
*/
|
|
public function unload_textdomain( string $textdomain = 'default', ?string $locale = null ): bool {
|
|
$unloaded = false;
|
|
|
|
if ( null !== $locale ) {
|
|
if ( isset( $this->loaded_translations[ $locale ][ $textdomain ] ) ) {
|
|
$unloaded = true;
|
|
foreach ( $this->loaded_translations[ $locale ][ $textdomain ] as $moe ) {
|
|
unset( $this->loaded_files[ $moe->get_file() ][ $locale ][ $textdomain ] );
|
|
}
|
|
}
|
|
|
|
unset( $this->loaded_translations[ $locale ][ $textdomain ] );
|
|
|
|
return $unloaded;
|
|
}
|
|
|
|
foreach ( $this->loaded_translations as $l => $domains ) {
|
|
if ( ! isset( $domains[ $textdomain ] ) ) {
|
|
continue;
|
|
}
|
|
|
|
$unloaded = true;
|
|
|
|
foreach ( $domains[ $textdomain ] as $moe ) {
|
|
unset( $this->loaded_files[ $moe->get_file() ][ $l ][ $textdomain ] );
|
|
}
|
|
|
|
unset( $this->loaded_translations[ $l ][ $textdomain ] );
|
|
}
|
|
|
|
return $unloaded;
|
|
}
|
|
|
|
/**
|
|
* Determines whether translations are loaded for a given text domain.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param string $textdomain Optional. Text domain. Default 'default'.
|
|
* @param string $locale Optional. Locale. Default current locale.
|
|
* @return bool True if there are any loaded translations, false otherwise.
|
|
*/
|
|
public function is_textdomain_loaded( string $textdomain = 'default', ?string $locale = null ): bool {
|
|
if ( null === $locale ) {
|
|
$locale = $this->current_locale;
|
|
}
|
|
|
|
return isset( $this->loaded_translations[ $locale ][ $textdomain ] ) &&
|
|
array() !== $this->loaded_translations[ $locale ][ $textdomain ];
|
|
}
|
|
|
|
/**
|
|
* Translates a singular string.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param string $text Text to translate.
|
|
* @param string $context Optional. Context for the string. Default empty string.
|
|
* @param string $textdomain Optional. Text domain. Default 'default'.
|
|
* @param string $locale Optional. Locale. Default current locale.
|
|
* @return string|false Translation on success, false otherwise.
|
|
*/
|
|
public function translate( string $text, string $context = '', string $textdomain = 'default', ?string $locale = null ) {
|
|
if ( '' !== $context ) {
|
|
$context .= "\4";
|
|
}
|
|
|
|
$translation = $this->locate_translation( "{$context}{$text}", $textdomain, $locale );
|
|
|
|
if ( false === $translation ) {
|
|
return false;
|
|
}
|
|
|
|
return $translation['entries'][0];
|
|
}
|
|
|
|
/**
|
|
* Translates plurals.
|
|
*
|
|
* Checks both singular+plural combinations as well as just singulars,
|
|
* in case the translation file does not store the plural.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param array $plurals {
|
|
* Pair of singular and plural translations.
|
|
*
|
|
* @type string $0 Singular translation.
|
|
* @type string $1 Plural translation.
|
|
* }
|
|
* @param int $number Number of items.
|
|
* @param string $context Optional. Context for the string. Default empty string.
|
|
* @param string $textdomain Optional. Text domain. Default 'default'.
|
|
* @param string|null $locale Optional. Locale. Default current locale.
|
|
* @return string|false Translation on success, false otherwise.
|
|
*/
|
|
public function translate_plural( array $plurals, int $number, string $context = '', string $textdomain = 'default', ?string $locale = null ) {
|
|
if ( '' !== $context ) {
|
|
$context .= "\4";
|
|
}
|
|
|
|
$text = implode( "\0", $plurals );
|
|
$translation = $this->locate_translation( "{$context}{$text}", $textdomain, $locale );
|
|
|
|
if ( false === $translation ) {
|
|
$text = $plurals[0];
|
|
$translation = $this->locate_translation( "{$context}{$text}", $textdomain, $locale );
|
|
|
|
if ( false === $translation ) {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
/** @var WP_Translation_File $source */
|
|
$source = $translation['source'];
|
|
$num = $source->get_plural_form( $number );
|
|
|
|
// See \Translations::translate_plural().
|
|
return $translation['entries'][ $num ] ?? $translation['entries'][0];
|
|
}
|
|
|
|
/**
|
|
* Returns all existing headers for a given text domain.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param string $textdomain Optional. Text domain. Default 'default'.
|
|
* @return array<string, string> Headers.
|
|
*/
|
|
public function get_headers( string $textdomain = 'default' ): array {
|
|
if ( array() === $this->loaded_translations ) {
|
|
return array();
|
|
}
|
|
|
|
$headers = array();
|
|
|
|
foreach ( $this->get_files( $textdomain ) as $moe ) {
|
|
foreach ( $moe->headers() as $header => $value ) {
|
|
$headers[ $this->normalize_header( $header ) ] = $value;
|
|
}
|
|
}
|
|
|
|
return $headers;
|
|
}
|
|
|
|
/**
|
|
* Normalizes header names to be capitalized.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param string $header Header name.
|
|
* @return string Normalized header name.
|
|
*/
|
|
protected function normalize_header( string $header ): string {
|
|
$parts = explode( '-', $header );
|
|
$parts = array_map( 'ucfirst', $parts );
|
|
return implode( '-', $parts );
|
|
}
|
|
|
|
/**
|
|
* Returns all entries for a given text domain.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param string $textdomain Optional. Text domain. Default 'default'.
|
|
* @return array<string, string> Entries.
|
|
*/
|
|
public function get_entries( string $textdomain = 'default' ): array {
|
|
if ( array() === $this->loaded_translations ) {
|
|
return array();
|
|
}
|
|
|
|
$entries = array();
|
|
|
|
foreach ( $this->get_files( $textdomain ) as $moe ) {
|
|
$entries = array_merge( $entries, $moe->entries() );
|
|
}
|
|
|
|
return $entries;
|
|
}
|
|
|
|
/**
|
|
* Locates translation for a given string and text domain.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param string $singular Singular translation.
|
|
* @param string $textdomain Optional. Text domain. Default 'default'.
|
|
* @param string $locale Optional. Locale. Default current locale.
|
|
* @return array{source: WP_Translation_File, entries: string[]}|false {
|
|
* Translations on success, false otherwise.
|
|
*
|
|
* @type WP_Translation_File $source Translation file instance.
|
|
* @type string[] $entries Array of translation entries.
|
|
* }
|
|
*/
|
|
protected function locate_translation( string $singular, string $textdomain = 'default', ?string $locale = null ) {
|
|
if ( array() === $this->loaded_translations ) {
|
|
return false;
|
|
}
|
|
|
|
// Find the translation in all loaded files for this text domain.
|
|
foreach ( $this->get_files( $textdomain, $locale ) as $moe ) {
|
|
$translation = $moe->translate( $singular );
|
|
if ( false !== $translation ) {
|
|
return array(
|
|
'entries' => explode( "\0", $translation ),
|
|
'source' => $moe,
|
|
);
|
|
}
|
|
if ( null !== $moe->error() ) {
|
|
// Unload this file, something is wrong.
|
|
$this->unload_file( $moe, $textdomain, $locale );
|
|
}
|
|
}
|
|
|
|
// Nothing could be found.
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Returns all translation files for a given text domain.
|
|
*
|
|
* @since 6.5.0
|
|
*
|
|
* @param string $textdomain Optional. Text domain. Default 'default'.
|
|
* @param string $locale Optional. Locale. Default current locale.
|
|
* @return WP_Translation_File[] List of translation files.
|
|
*/
|
|
protected function get_files( string $textdomain = 'default', ?string $locale = null ): array {
|
|
if ( null === $locale ) {
|
|
$locale = $this->current_locale;
|
|
}
|
|
|
|
return $this->loaded_translations[ $locale ][ $textdomain ] ?? array();
|
|
}
|
|
|
|
/**
|
|
* Returns a boolean to indicate whether a translation exists for a given string with optional text domain and locale.
|
|
*
|
|
* @since 6.7.0
|
|
*
|
|
* @param string $singular Singular translation to check.
|
|
* @param string $textdomain Optional. Text domain. Default 'default'.
|
|
* @param ?string $locale Optional. Locale. Default current locale.
|
|
* @return bool True if the translation exists, false otherwise.
|
|
*/
|
|
public function has_translation( string $singular, string $textdomain = 'default', ?string $locale = null ): bool {
|
|
if ( null === $locale ) {
|
|
$locale = $this->current_locale;
|
|
}
|
|
|
|
return false !== $this->locate_translation( $singular, $textdomain, $locale );
|
|
}
|
|
}
|