[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/ -> l10n.php (summary)

Core Translation API

File Size: 2010 lines (68 kb)
Included or required: 1 time
Referenced: 0 times
Includes or requires: 1 file
 wp-admin/includes/translation-install.php

Defines 49 functions

  get_locale()
  get_user_locale()
  determine_locale()
  translate()
  before_last_bar()
  translate_with_gettext_context()
  __()
  esc_attr__()
  esc_html__()
  _e()
  esc_attr_e()
  esc_html_e()
  _x()
  _ex()
  esc_attr_x()
  esc_html_x()
  _n()
  _nx()
  _n_noop()
  _nx_noop()
  translate_nooped_plural()
  load_textdomain()
  unload_textdomain()
  load_default_textdomain()
  load_plugin_textdomain()
  load_muplugin_textdomain()
  load_theme_textdomain()
  load_child_theme_textdomain()
  load_script_textdomain()
  load_script_translations()
  _load_textdomain_just_in_time()
  get_translations_for_domain()
  is_textdomain_loaded()
  translate_user_role()
  get_available_languages()
  wp_get_installed_translations()
  wp_get_pomo_file_data()
  wp_get_l10n_php_file_data()
  wp_dropdown_languages()
  is_rtl()
  switch_to_locale()
  switch_to_user_locale()
  restore_previous_locale()
  restore_current_locale()
  is_locale_switched()
  translate_settings_using_i18n_schema()
  wp_get_list_item_separator()
  wp_get_word_count_type()
  has_translation()

Functions
Functions that are not part of a class:

get_locale()   X-Ref
Retrieves the current locale.

If the locale is set, then it will filter the locale in the {@see 'locale'}
filter hook and return the value.

If the locale is not set already, then the WPLANG constant is used if it is
defined. Then it is filtered through the {@see 'locale'} filter hook and
the value for the locale global set and the locale is returned.

The process to get the locale should only be done once, but the locale will
always be filtered using the {@see 'locale'} hook.

return: string The locale of the blog or from the {@see 'locale'} hook.

get_user_locale( $user = 0 )   X-Ref
Retrieves the locale of a user.

If the user has a locale set to a non-empty string then it will be
returned. Otherwise it returns the locale of get_locale().

return: string The locale of the user.
param: int|WP_User $user User's ID or a WP_User object. Defaults to current user.

determine_locale()   X-Ref
Determines the current locale desired for the request.

return: string The determined locale.

translate( $text, $domain = 'default' )   X-Ref
Retrieves the translation of $text.

If there is no translation, or the text domain isn't loaded, the original text is returned.

*Note:* Don't use translate() directly, use __() or related functions.

return: string Translated text.
param: string $text   Text to translate.
param: string $domain Optional. Text domain. Unique identifier for retrieving translated strings.

before_last_bar( $text )   X-Ref
Removes last item on a pipe-delimited string.

Meant for removing the last item in a string, such as 'Role name|User role'. The original
string will be returned if no pipe '|' characters are found in the string.

return: string Either $text or everything before the last pipe.
param: string $text A pipe-delimited string.

translate_with_gettext_context( $text, $context, $domain = 'default' )   X-Ref
Retrieves the translation of $text in the context defined in $context.

If there is no translation, or the text domain isn't loaded, the original text is returned.

*Note:* Don't use translate_with_gettext_context() directly, use _x() or related functions.

return: string Translated text on success, original text on failure.
param: string $text    Text to translate.
param: string $context Context information for the translators.
param: string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.

__( $text, $domain = 'default' )   X-Ref
Retrieves the translation of $text.

If there is no translation, or the text domain isn't loaded, the original text is returned.

return: string Translated text.
param: string $text   Text to translate.
param: string $domain Optional. Text domain. Unique identifier for retrieving translated strings.

esc_attr__( $text, $domain = 'default' )   X-Ref
Retrieves the translation of $text and escapes it for safe use in an attribute.

If there is no translation, or the text domain isn't loaded, the original text is returned.

return: string Translated text on success, original text on failure.
param: string $text   Text to translate.
param: string $domain Optional. Text domain. Unique identifier for retrieving translated strings.

esc_html__( $text, $domain = 'default' )   X-Ref
Retrieves the translation of $text and escapes it for safe use in HTML output.

If there is no translation, or the text domain isn't loaded, the original text
is escaped and returned.

return: string Translated text.
param: string $text   Text to translate.
param: string $domain Optional. Text domain. Unique identifier for retrieving translated strings.

_e( $text, $domain = 'default' )   X-Ref
Displays translated text.

param: string $text   Text to translate.
param: string $domain Optional. Text domain. Unique identifier for retrieving translated strings.

esc_attr_e( $text, $domain = 'default' )   X-Ref
Displays translated text that has been escaped for safe use in an attribute.

Encodes `< > & " '` (less than, greater than, ampersand, double quote, single quote).
Will never double encode entities.

If you need the value for use in PHP, use esc_attr__().

param: string $text   Text to translate.
param: string $domain Optional. Text domain. Unique identifier for retrieving translated strings.

esc_html_e( $text, $domain = 'default' )   X-Ref
Displays translated text that has been escaped for safe use in HTML output.

If there is no translation, or the text domain isn't loaded, the original text
is escaped and displayed.

If you need the value for use in PHP, use esc_html__().

param: string $text   Text to translate.
param: string $domain Optional. Text domain. Unique identifier for retrieving translated strings.

_x( $text, $context, $domain = 'default' )   X-Ref
Retrieves translated string with gettext context.

Quite a few times, there will be collisions with similar translatable text
found in more than two places, but with different translated context.

By including the context in the pot file, translators can translate the two
strings differently.

return: string Translated context string without pipe.
param: string $text    Text to translate.
param: string $context Context information for the translators.
param: string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.

_ex( $text, $context, $domain = 'default' )   X-Ref
Displays translated string with gettext context.

param: string $text    Text to translate.
param: string $context Context information for the translators.
param: string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.

esc_attr_x( $text, $context, $domain = 'default' )   X-Ref
Translates string with gettext context, and escapes it for safe use in an attribute.

If there is no translation, or the text domain isn't loaded, the original text
is escaped and returned.

return: string Translated text.
param: string $text    Text to translate.
param: string $context Context information for the translators.
param: string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.

esc_html_x( $text, $context, $domain = 'default' )   X-Ref
Translates string with gettext context, and escapes it for safe use in HTML output.

If there is no translation, or the text domain isn't loaded, the original text
is escaped and returned.

return: string Translated text.
param: string $text    Text to translate.
param: string $context Context information for the translators.
param: string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.

_n( $single, $plural, $number, $domain = 'default' )   X-Ref
Translates and retrieves the singular or plural form based on the supplied number.

Used when you want to use the appropriate form of a string based on whether a
number is singular or plural.

Example:

printf( _n( '%s person', '%s people', $count, 'text-domain' ), number_format_i18n( $count ) );

return: string The translated singular or plural form.
param: string $single The text to be used if the number is singular.
param: string $plural The text to be used if the number is plural.
param: int    $number The number to compare against to use either the singular or plural form.
param: string $domain Optional. Text domain. Unique identifier for retrieving translated strings.

_nx( $single, $plural, $number, $context, $domain = 'default' )   X-Ref
Translates and retrieves the singular or plural form based on the supplied number, with gettext context.

This is a hybrid of _n() and _x(). It supports context and plurals.

Used when you want to use the appropriate form of a string with context based on whether a
number is singular or plural.

Example of a generic phrase which is disambiguated via the context parameter:

printf( _nx( '%s group', '%s groups', $people, 'group of people', 'text-domain' ), number_format_i18n( $people ) );
printf( _nx( '%s group', '%s groups', $animals, 'group of animals', 'text-domain' ), number_format_i18n( $animals ) );

return: string The translated singular or plural form.
param: string $single  The text to be used if the number is singular.
param: string $plural  The text to be used if the number is plural.
param: int    $number  The number to compare against to use either the singular or plural form.
param: string $context Context information for the translators.
param: string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.

_n_noop( $singular, $plural, $domain = null )   X-Ref
Registers plural strings in POT file, but does not translate them.

Used when you want to keep structures with translatable plural
strings and use them later when the number is known.

Example:

$message = _n_noop( '%s post', '%s posts', 'text-domain' );
...
printf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );

return: array {
param: string $singular Singular form to be localized.
param: string $plural   Plural form to be localized.
param: string $domain   Optional. Text domain. Unique identifier for retrieving translated strings.

_nx_noop( $singular, $plural, $context, $domain = null )   X-Ref
Registers plural strings with gettext context in POT file, but does not translate them.

Used when you want to keep structures with translatable plural
strings and use them later when the number is known.

Example of a generic phrase which is disambiguated via the context parameter:

$messages = array(
'people'  => _nx_noop( '%s group', '%s groups', 'people', 'text-domain' ),
'animals' => _nx_noop( '%s group', '%s groups', 'animals', 'text-domain' ),
);
...
$message = $messages[ $type ];
printf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );

return: array {
param: string $singular Singular form to be localized.
param: string $plural   Plural form to be localized.
param: string $context  Context information for the translators.
param: string $domain   Optional. Text domain. Unique identifier for retrieving translated strings.

translate_nooped_plural( $nooped_plural, $count, $domain = 'default' )   X-Ref
Translates and returns the singular or plural form of a string that's been registered
with _n_noop() or _nx_noop().

Used when you want to use a translatable plural string once the number is known.

Example:

$message = _n_noop( '%s post', '%s posts', 'text-domain' );
...
printf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );

return: string Either $singular or $plural translated text.
param: array  $nooped_plural {
param: int    $count         Number of objects.
param: string $domain        Optional. Text domain. Unique identifier for retrieving translated strings. If $nooped_plural contains

load_textdomain( $domain, $mofile, $locale = null )   X-Ref
Loads a .mo file into the text domain $domain.

If the text domain already exists, the translations will be merged. If both
sets have the same string, the translation from the original value will be taken.

On success, the .mo file will be placed in the $l10n global by $domain
and will be a MO object.

return: bool True on success, false on failure.
param: string $domain Text domain. Unique identifier for retrieving translated strings.
param: string $mofile Path to the .mo file.
param: string $locale Optional. Locale. Default is the current locale.

unload_textdomain( $domain, $reloadable = false )   X-Ref
Unloads translations for a text domain.

return: bool Whether textdomain was unloaded.
param: string $domain     Text domain. Unique identifier for retrieving translated strings.
param: bool   $reloadable Whether the text domain can be loaded just-in-time again.

load_default_textdomain( $locale = null )   X-Ref
Loads default translated strings based on locale.

Loads the .mo file in WP_LANG_DIR constant path from WordPress root.
The translated (.mo) file is named based on the locale.

return: bool Whether the textdomain was loaded.
param: string $locale Optional. Locale to load. Default is the value of get_locale().

load_plugin_textdomain( $domain, $deprecated = false, $plugin_rel_path = false )   X-Ref
Loads a plugin's translated strings.

If the path is not given then it will be the root of the plugin directory.

The .mo file should be named based on the text domain with a dash, and then the locale exactly.

return: bool True when textdomain is successfully loaded, false otherwise.
param: string       $domain          Unique identifier for retrieving translated strings
param: string|false $deprecated      Optional. Deprecated. Use the $plugin_rel_path parameter instead.
param: string|false $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR where the .mo file resides.

load_muplugin_textdomain( $domain, $mu_plugin_rel_path = '' )   X-Ref
Loads the translated strings for a plugin residing in the mu-plugins directory.

return: bool True when textdomain is successfully loaded, false otherwise.
param: string $domain             Text domain. Unique identifier for retrieving translated strings.
param: string $mu_plugin_rel_path Optional. Relative to `WPMU_PLUGIN_DIR` directory in which the .mo

load_theme_textdomain( $domain, $path = false )   X-Ref
Loads the theme's translated strings.

If the current locale exists as a .mo file in the theme's root directory, it
will be included in the translated strings by the $domain.

The .mo files must be named based on the locale exactly.

return: bool True when textdomain is successfully loaded, false otherwise.
param: string       $domain Text domain. Unique identifier for retrieving translated strings.
param: string|false $path   Optional. Path to the directory containing the .mo file.

load_child_theme_textdomain( $domain, $path = false )   X-Ref
Loads the child theme's translated strings.

If the current locale exists as a .mo file in the child theme's
root directory, it will be included in the translated strings by the $domain.

The .mo files must be named based on the locale exactly.

return: bool True when the theme textdomain is successfully loaded, false otherwise.
param: string       $domain Text domain. Unique identifier for retrieving translated strings.
param: string|false $path   Optional. Path to the directory containing the .mo file.

load_script_textdomain( $handle, $domain = 'default', $path = '' )   X-Ref
Loads the script translated strings.

return: string|false The translated strings in JSON encoding on success,
param: string $handle Name of the script to register a translation domain to.
param: string $domain Optional. Text domain. Default 'default'.
param: string $path   Optional. The full file path to the directory containing translation files.

load_script_translations( $file, $handle, $domain )   X-Ref
Loads the translation data for the given script handle and text domain.

return: string|false The JSON-encoded translated strings for the given script handle and text domain.
param: string|false $file   Path to the translation file to load. False if there isn't one.
param: string       $handle Name of the script to register a translation domain to.
param: string       $domain The text domain.

_load_textdomain_just_in_time( $domain )   X-Ref
Loads plugin and theme text domains just-in-time.

When a textdomain is encountered for the first time, we try to load
the translation file from `wp-content/languages`, removing the need
to call load_plugin_textdomain() or load_theme_textdomain().

return: bool True when the textdomain is successfully loaded, false otherwise.
param: string $domain Text domain. Unique identifier for retrieving translated strings.

get_translations_for_domain( $domain )   X-Ref
Returns the Translations instance for a text domain.

If there isn't one, returns empty Translations instance.

return: Translations|NOOP_Translations A Translations instance.
param: string $domain Text domain. Unique identifier for retrieving translated strings.

is_textdomain_loaded( $domain )   X-Ref
Determines whether there are translations for the text domain.

return: bool Whether there are translations.
param: string $domain Text domain. Unique identifier for retrieving translated strings.

translate_user_role( $name, $domain = 'default' )   X-Ref
Translates role name.

Since the role names are in the database and not in the source there
are dummy gettext calls to get them into the POT file and this function
properly translates them back.

The before_last_bar() call is needed, because older installations keep the roles
using the old context format: 'Role name|User role' and just skipping the
content after the last bar is easier than fixing them in the DB. New installations
won't suffer from that problem.

return: string Translated role name on success, original name on failure.
param: string $name   The role name.
param: string $domain Optional. Text domain. Unique identifier for retrieving translated strings.

get_available_languages( $dir = null )   X-Ref
Gets all available languages based on the presence of *.mo and *.l10n.php files in a given directory.

The default directory is WP_LANG_DIR.

return: string[] An array of language codes or an empty array if no languages are present.
param: string $dir A directory to search for language files.

wp_get_installed_translations( $type )   X-Ref
Gets installed translations.

Looks in the wp-content/languages directory for translations of
plugins or themes.

return: array Array of language data.
param: string $type What to search for. Accepts 'plugins', 'themes', 'core'.

wp_get_pomo_file_data( $po_file )   X-Ref
Extracts headers from a PO file.

return: string[] Array of PO file header values keyed by header name.
param: string $po_file Path to PO file.

wp_get_l10n_php_file_data( $php_file )   X-Ref
Extracts headers from a PHP translation file.

return: string[] Array of file header values keyed by header name.
param: string $php_file Path to a `.l10n.php` file.

wp_dropdown_languages( $args = array()   X-Ref
Displays or returns a Language selector.

return: string HTML dropdown list of languages.
param: string|array $args {

is_rtl()   X-Ref
Determines whether the current locale is right-to-left (RTL).

For more information on this and similar theme functions, check out
the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
Conditional Tags} article in the Theme Developer Handbook.

return: bool Whether locale is RTL.

switch_to_locale( $locale )   X-Ref
Switches the translations according to the given locale.

return: bool True on success, false on failure.
param: string $locale The locale.

switch_to_user_locale( $user_id )   X-Ref
Switches the translations according to the given user's locale.

return: bool True on success, false on failure.
param: int $user_id User ID.

restore_previous_locale()   X-Ref
Restores the translations according to the previous locale.

return: string|false Locale on success, false on error.

restore_current_locale()   X-Ref
Restores the translations according to the original locale.

return: string|false Locale on success, false on error.

is_locale_switched()   X-Ref
Determines whether switch_to_locale() is in effect.

return: bool True if the locale has been switched, false otherwise.

translate_settings_using_i18n_schema( $i18n_schema, $settings, $textdomain )   X-Ref
Translates the provided settings value using its i18n schema.

return: string|string[]|array[] Translated settings.
param: string|string[]|array[]|object $i18n_schema I18n schema for the setting.
param: string|string[]|array[]        $settings    Value for the settings.
param: string                         $textdomain  Textdomain to use with translations.

wp_get_list_item_separator()   X-Ref
Retrieves the list item separator based on the locale.

return: string Locale-specific list item separator.

wp_get_word_count_type()   X-Ref
Retrieves the word count type based on the locale.

return: string Locale-specific word count type. Possible values are `characters_excluding_spaces`,

has_translation( string $singular, string $textdomain = 'default', ?string $locale = null )   X-Ref
Returns a boolean to indicate whether a translation exists for a given string with optional text domain and locale.

return: bool  True if the translation exists, false otherwise.
param: string  $singular   Singular translation to check.
param: string  $textdomain Optional. Text domain. Default 'default'.
param: ?string $locale     Optional. Locale. Default current locale.



Generated : Mon Dec 23 08:20:01 2024 Cross-referenced by PHPXref