wp-includes/l10n.php

   1 <?php
   2 /**
   3  * WordPress Translation API
   4  *
   5  * @package WordPress
   6  * @subpackage i18n
   7  */
   8
   9 /**
  10  * Gets the current locale.
  11  *
  12  * If the locale is set, then it will filter the locale in the 'locale' filter
  13  * hook and return the value.
  14  *
  15  * If the locale is not set already, then the WPLANG constant is used if it is
  16  * defined. Then it is filtered through the 'locale' filter hook and the value
  17  * for the locale global set and the locale is returned.
  18  *
  19  * The process to get the locale should only be done once but the locale will
  20  * always be filtered using the 'locale' hook.
  21  *
  22  * @since 1.5.0
  23  * @uses apply_filters() Calls 'locale' hook on locale value.
  24  * @uses $locale Gets the locale stored in the global.
  25  *
  26  * @return string The locale of the blog or from the 'locale' hook.
  27  */
  28 function get_locale() {
  29         global $locale;
  30
  31         if (isset($locale))
  32                 return apply_filters( 'locale', $locale );
  33
  34         // WPLANG is defined in wp-config.
  35         if (defined('WPLANG'))
  36                 $locale = WPLANG;
  37
  38         if (empty($locale))
  39                 $locale = 'en_US';
  40
  41         return apply_filters('locale', $locale);
  42 }
  43
  44 /**
  45  * Retrieves the translation of $text. If there is no translation, or
  46  * the domain isn't loaded the original text is returned.
  47  *
  48  * @see __() Don't use translate() directly, use __()
  49  * @since 2.2.0
  50  * @uses apply_filters() Calls 'gettext' on domain translated text
  51  *              with the untranslated text as second parameter.
  52  *
  53  * @param string $text Text to translate.
  54  * @param string $domain Domain to retrieve the translated text.
  55  * @return string Translated text
  56  */
  57 function translate( $text, $domain = 'default' ) {
  58         $translations = &get_translations_for_domain( $domain );
  59         return apply_filters('gettext', $translations->translate($text), $text, $domain);
  60 }
  61
  62 function before_last_bar( $string ) {
  63         $last_bar = strrpos( $string, '|' );
  64         if ( false == $last_bar )
  65                 return $string;
  66         else
  67                 return substr( $string, 0, $last_bar );
  68 }
  69
  70 /**
  71  * Translates $text like translate(), but assumes that the text
  72  * contains a context after its last vertical bar.
  73  *
  74  * @since 2.5
  75  * @uses translate()
  76  *
  77  * @param string $text Text to translate
  78  * @param string $domain Domain to retrieve the translated text
  79  * @return string Translated text
  80  */
  81 function translate_with_context( $text, $domain = 'default' ) {
  82         return before_last_bar( translate( $text, $domain ) );
  83
  84 }
  85
  86 function translate_with_gettext_context( $text, $context, $domain = 'default' ) {
  87         $translations = &get_translations_for_domain( $domain );
  88         return apply_filters( 'gettext_with_context', $translations->translate( $text, $context ), $text, $context, $domain);
  89 }
  90
  91 /**
  92  * Retrieves the translation of $text. If there is no translation, or
  93  * the domain isn't loaded the original text is returned.
  94  *
  95  * @see translate() An alias of translate()
  96  * @since 2.1.0
  97  *
  98  * @param string $text Text to translate
  99  * @param string $domain Optional. Domain to retrieve the translated text
 100  * @return string Translated text
 101  */
 102 function __( $text, $domain = 'default' ) {
 103         return translate( $text, $domain );
 104 }
 105
 106 /**
 107  * Retrieves the translation of $text and escapes it for safe use in an attribute.
 108  * If there is no translation, or the domain isn't loaded the original text is returned.
 109  *
 110  * @see translate() An alias of translate()
 111  * @see esc_attr()
 112  * @since 2.8.0
 113  *
 114  * @param string $text Text to translate
 115  * @param string $domain Optional. Domain to retrieve the translated text
 116  * @return string Translated text
 117  */
 118 function esc_attr__( $text, $domain = 'default' ) {
 119         return esc_attr( translate( $text, $domain ) );
 120 }
 121
 122 /**
 123  * Retrieves the translation of $text and escapes it for safe use in HTML output.
 124  * If there is no translation, or the domain isn't loaded the original text is returned.
 125  *
 126  * @see translate() An alias of translate()
 127  * @see esc_html()
 128  * @since 2.8.0
 129  *
 130  * @param string $text Text to translate
 131  * @param string $domain Optional. Domain to retrieve the translated text
 132  * @return string Translated text
 133  */
 134 function esc_html__( $text, $domain = 'default' ) {
 135         return esc_html( translate( $text, $domain ) );
 136 }
 137
 138 /**
 139  * Displays the returned translated text from translate().
 140  *
 141  * @see translate() Echoes returned translate() string
 142  * @since 1.2.0
 143  *
 144  * @param string $text Text to translate
 145  * @param string $domain Optional. Domain to retrieve the translated text
 146  */
 147 function _e( $text, $domain = 'default' ) {
 148         echo translate( $text, $domain );
 149 }
 150
 151 /**
 152  * Displays translated text that has been escaped for safe use in an attribute.
 153  *
 154  * @see translate() Echoes returned translate() string
 155  * @see esc_attr()
 156  * @since 2.8.0
 157  *
 158  * @param string $text Text to translate
 159  * @param string $domain Optional. Domain to retrieve the translated text
 160  */
 161 function esc_attr_e( $text, $domain = 'default' ) {
 162         echo esc_attr( translate( $text, $domain ) );
 163 }
 164
 165 /**
 166  * Displays translated text that has been escaped for safe use in HTML output.
 167  *
 168  * @see translate() Echoes returned translate() string
 169  * @see esc_html()
 170  * @since 2.8.0
 171  *
 172  * @param string $text Text to translate
 173  * @param string $domain Optional. Domain to retrieve the translated text
 174  */
 175 function esc_html_e( $text, $domain = 'default' ) {
 176         echo esc_html( translate( $text, $domain ) );
 177 }
 178
 179 /**
 180  * Retrieve translated string with vertical bar context
 181  *
 182  * Quite a few times, there will be collisions with similar translatable text
 183  * found in more than two places but with different translated context.
 184  *
 185  * In order to use the separate contexts, the _c() function is used and the
 186  * translatable string uses a pipe ('|') which has the context the string is in.
 187  *
 188  * When the translated string is returned, it is everything before the pipe, not
 189  * including the pipe character. If there is no pipe in the translated text then
 190  * everything is returned.
 191  *
 192  * @since 2.2.0
 193  *
 194  * @param string $text Text to translate
 195  * @param string $domain Optional. Domain to retrieve the translated text
 196  * @return string Translated context string without pipe
 197  */
 198 function _c($text, $domain = 'default') {
 199         return translate_with_context($text, $domain);
 200 }
 201
 202 function _x( $single, $context, $domain = 'default' ) {
 203         return translate_with_gettext_context( $single, $context, $domain );
 204 }
 205
 206 function esc_attr_x( $single, $context, $domain = 'default' ) {
 207         return esc_attr( translate_with_gettext_context( $single, $context, $domain ) );
 208 }
 209
 210 function __ngettext() {
 211         _deprecated_function( __FUNCTION__, '2.8', '_n()' );
 212         $args = func_get_args();
 213         return call_user_func_array('_n', $args);
 214 }
 215
 216 /**
 217  * Retrieve the plural or single form based on the amount.
 218  *
 219  * If the domain is not set in the $l10n list, then a comparison will be made
 220  * and either $plural or $single parameters returned.
 221  *
 222  * If the domain does exist, then the parameters $single, $plural, and $number
 223  * will first be passed to the domain's ngettext method. Then it will be passed
 224  * to the 'ngettext' filter hook along with the same parameters. The expected
 225  * type will be a string.
 226  *
 227  * @since 1.2.0
 228  * @uses $l10n Gets list of domain translated string (gettext_reader) objects
 229  * @uses apply_filters() Calls 'ngettext' hook on domains text returned,
 230  *              along with $single, $plural, and $number parameters. Expected to return string.
 231  *
 232  * @param string $single The text that will be used if $number is 1
 233  * @param string $plural The text that will be used if $number is not 1
 234  * @param int $number The number to compare against to use either $single or $plural
 235  * @param string $domain Optional. The domain identifier the text should be retrieved in
 236  * @return string Either $single or $plural translated text
 237  */
 238 function _n($single, $plural, $number, $domain = 'default') {
 239         $translations = &get_translations_for_domain( $domain );
 240         $translation = $translations->translate_plural( $single, $plural, $number );
 241         return apply_filters( 'ngettext', $translation, $single, $plural, $number, $domain );
 242 }
 243
 244 /**
 245  * @see _n() A version of _n(), which supports contexts --
 246  * strips everything from the translation after the last bar
 247  *
 248  */
 249 function _nc( $single, $plural, $number, $domain = 'default' ) {
 250         return before_last_bar( _n( $single, $plural, $number, $domain ) );
 251 }
 252
 253 function _nx($single, $plural, $number, $context, $domain = 'default') {
 254         $translations = &get_translations_for_domain( $domain );
 255         $translation = $translations->translate_plural( $single, $plural, $number, $context );
 256         return apply_filters( 'ngettext_with_context ', $translation, $single, $plural, $number, $context, $domain );
 257 }
 258
 259 /**
 260  * @deprecated Use _n_noop()
 261  */
 262 function __ngettext_noop() {
 263         _deprecated_function( __FUNCTION__, '2.8', '_n_noop()' );
 264         $args = func_get_args();
 265         return call_user_func_array('_n_noop', $args);
 266
 267 }
 268
 269 /**
 270  * Register plural strings in POT file, but don't translate them.
 271  *
 272  * Used when you want do keep structures with translatable plural strings and
 273  * use them later.
 274  *
 275  * Example:
 276  *  $messages = array(
 277  *      'post' => _n_noop('%s post', '%s posts'),
 278  *      'page' => _n_noop('%s pages', '%s pages')
 279  *  );
 280  *  ...
 281  *  $message = $messages[$type];
 282  *  $usable_text = sprintf(_n($message[0], $message[1], $count), $count);
 283  *
 284  * @since 2.5
 285  * @param $single Single form to be i18ned
 286  * @param $plural Plural form to be i18ned
 287  * @return array array($single, $plural)
 288  */
 289 function _n_noop( $single, $plural ) {
 290         return array( $single, $plural );
 291 }
 292
 293 /**
 294  * Register plural strings with context in POT file, but don't translate them.
 295  *
 296  * @see _n_noop()
 297  */
 298 function _nx_noop( $single, $plural, $context ) {
 299         return array( $single, $plural, $context );
 300 }
 301
 302
 303 /**
 304  * Loads MO file into the list of domains.
 305  *
 306  * If the domain already exists, the inclusion will fail. If the MO file is not
 307  * readable, the inclusion will fail.
 308  *
 309  * On success, the .mo file will be placed in the $l10n global by $domain
 310  * and will be an gettext_reader object.
 311  *
 312  * @since 1.5.0
 313  * @uses $l10n Gets list of domain translated string (gettext_reader) objects
 314  * @uses CacheFileReader Reads the MO file
 315  * @uses gettext_reader Allows for retrieving translated strings
 316  *
 317  * @param string $domain Unique identifier for retrieving translated strings
 318  * @param string $mofile Path to the .mo file
 319  * @return null On failure returns null and also on success returns nothing.
 320  */
 321 function load_textdomain($domain, $mofile) {
 322         global $l10n;
 323
 324         if ( !is_readable($mofile)) return;
 325
 326         $mo = new MO();
 327         $mo->import_from_file( $mofile );
 328
 329         if (isset($l10n[$domain]))
 330                 $mo->merge_with( $l10n[$domain] );
 331
 332         $l10n[$domain] = &$mo;
 333 }
 334
 335 /**
 336  * Loads default translated strings based on locale.
 337  *
 338  * Loads the .mo file in WP_LANG_DIR constant path from WordPress root. The
 339  * translated (.mo) file is named based off of the locale.
 340  *
 341  * @since 1.5.0
 342  */
 343 function load_default_textdomain() {
 344         $locale = get_locale();
 345
 346         $mofile = WP_LANG_DIR . "/$locale.mo";
 347
 348         load_textdomain('default', $mofile);
 349 }
 350
 351 /**
 352  * Loads the plugin's translated strings.
 353  *
 354  * If the path is not given then it will be the root of the plugin directory.
 355  * The .mo file should be named based on the domain with a dash, and then the locale exactly.
 356  *
 357  * @since 1.5.0
 358  *
 359  * @param string $domain Unique identifier for retrieving translated strings
 360  * @param string $abs_rel_path Optional. Relative path to ABSPATH of a folder,
 361  *      where the .mo file resides. Deprecated, but still functional until 2.7
 362  * @param string $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR. This is the preferred argument to use. It takes precendence over $abs_rel_path
 363  */
 364 function load_plugin_textdomain($domain, $abs_rel_path = false, $plugin_rel_path = false) {
 365         $locale = get_locale();
 366
 367         if ( false !== $plugin_rel_path )
 368                 $path = WP_PLUGIN_DIR . '/' . trim( $plugin_rel_path, '/');
 369         else if ( false !== $abs_rel_path)
 370                 $path = ABSPATH . trim( $abs_rel_path, '/');
 371         else
 372                 $path = WP_PLUGIN_DIR;
 373
 374         $mofile = $path . '/'. $domain . '-' . $locale . '.mo';
 375         load_textdomain($domain, $mofile);
 376 }
 377
 378 /**
 379  * Loads the theme's translated strings.
 380  *
 381  * If the current locale exists as a .mo file in the theme's root directory, it
 382  * will be included in the translated strings by the $domain.
 383  *
 384  * The .mo files must be named based on the locale exactly.
 385  *
 386  * @since 1.5.0
 387  *
 388  * @param string $domain Unique identifier for retrieving translated strings
 389  */
 390 function load_theme_textdomain($domain, $path = false) {
 391         $locale = get_locale();
 392
 393         $path = ( empty( $path ) ) ? get_template_directory() : $path;
 394
 395         $mofile = "$path/$locale.mo";
 396         load_textdomain($domain, $mofile);
 397 }
 398
 399 /**
 400  * Returns the Translations instance for a domain. If there isn't one,
 401  * returns empty Translations instance.
 402  *
 403  * @param string $domain
 404  * @return object A Translation instance
 405  */
 406 function &get_translations_for_domain( $domain ) {
 407         global $l10n;
 408         $empty = &new Translations;
 409         if ( isset($l10n[$domain]) )
 410                 return $l10n[$domain];
 411         else
 412                 return $empty;
 413 }
 414
 415 /**
 416  * Translates role name. Since the role names are in the database and
 417  * not in the source there are dummy gettext calls to get them into the POT
 418  * file and this function properly translates them back.
 419  *
 420  * The before_last_bar() call is needed, because older installs keep the roles
 421  * using the old context format: 'Role name|User role' and just skipping the
 422  * content after the last bar is easier than fixing them in the DB. New installs
 423  * won't suffer from that problem.
 424  */
 425 function translate_user_role( $name ) {
 426         return before_last_bar( translate_with_gettext_context( $name, 'User role' ) );
 427 }
 428 ?>