Title: WP_Translation_Controller
Published: April 3, 2024
Last modified: February 24, 2026

---

# class WP_Translation_Controller {}

## In this article

 * [Methods](https://developer.wordpress.org/reference/classes/wp_translation_controller/?output_format=md#methods)
 * [Source](https://developer.wordpress.org/reference/classes/wp_translation_controller/?output_format=md#source)
 * [Changelog](https://developer.wordpress.org/reference/classes/wp_translation_controller/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/classes/wp_translation_controller/?output_format=md#wp--skip-link--target)

Class [WP_Translation_Controller](https://developer.wordpress.org/reference/classes/wp_translation_controller/).

## 󠀁[Methods](https://developer.wordpress.org/reference/classes/wp_translation_controller/?output_format=md#methods)󠁿

| Name | Description | 
| [WP_Translation_Controller::get_entries](https://developer.wordpress.org/reference/classes/wp_translation_controller/get_entries/) | Returns all entries for a given text domain. | 
| [WP_Translation_Controller::get_files](https://developer.wordpress.org/reference/classes/wp_translation_controller/get_files/) | Returns all translation files for a given text domain. | 
| [WP_Translation_Controller::get_headers](https://developer.wordpress.org/reference/classes/wp_translation_controller/get_headers/) | Returns all existing headers for a given text domain. | 
| [WP_Translation_Controller::get_instance](https://developer.wordpress.org/reference/classes/wp_translation_controller/get_instance/) | Utility method to retrieve the main instance of the class. | 
| [WP_Translation_Controller::get_locale](https://developer.wordpress.org/reference/classes/wp_translation_controller/get_locale/) | Returns the current locale. | 
| [WP_Translation_Controller::has_translation](https://developer.wordpress.org/reference/classes/wp_translation_controller/has_translation/) | Returns a boolean to indicate whether a translation exists for a given string with optional text domain and locale. | 
| [WP_Translation_Controller::is_textdomain_loaded](https://developer.wordpress.org/reference/classes/wp_translation_controller/is_textdomain_loaded/) | Determines whether translations are loaded for a given text domain. | 
| [WP_Translation_Controller::load_file](https://developer.wordpress.org/reference/classes/wp_translation_controller/load_file/) | Loads a translation file for a given text domain. | 
| [WP_Translation_Controller::locate_translation](https://developer.wordpress.org/reference/classes/wp_translation_controller/locate_translation/) | Locates translation for a given string and text domain. | 
| [WP_Translation_Controller::normalize_header](https://developer.wordpress.org/reference/classes/wp_translation_controller/normalize_header/) | Normalizes header names to be capitalized. | 
| [WP_Translation_Controller::set_locale](https://developer.wordpress.org/reference/classes/wp_translation_controller/set_locale/) | Sets the current locale. | 
| [WP_Translation_Controller::translate](https://developer.wordpress.org/reference/classes/wp_translation_controller/translate/) | Translates a singular string. | 
| [WP_Translation_Controller::translate_plural](https://developer.wordpress.org/reference/classes/wp_translation_controller/translate_plural/) | Translates plurals. | 
| [WP_Translation_Controller::unload_file](https://developer.wordpress.org/reference/classes/wp_translation_controller/unload_file/) | Unloads a translation file for a given text domain. | 
| [WP_Translation_Controller::unload_textdomain](https://developer.wordpress.org/reference/classes/wp_translation_controller/unload_textdomain/) | Unloads all translation files for a given text domain. |

## 󠀁[Source](https://developer.wordpress.org/reference/classes/wp_translation_controller/?output_format=md#source)󠁿

    ```php
    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 );
    	}
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/l10n/class-wp-translation-controller.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/l10n/class-wp-translation-controller.php#L15)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/l10n/class-wp-translation-controller.php#L15-L455)

## 󠀁[Changelog](https://developer.wordpress.org/reference/classes/wp_translation_controller/?output_format=md#changelog)󠁿

| Version | Description | 
| [6.5.0](https://developer.wordpress.org/reference/since/6.5.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fclasses%2Fwp_translation_controller%2F)
before being able to contribute a note or feedback.