[Summary view] [Print] [Text view]

   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  function translate_with_gettext_context( $text, $context, $domain = 'default' ) {
  86      $translations = &get_translations_for_domain( $domain );
  87      return apply_filters( 'gettext_with_context', $translations->translate( $text, $context ), $text, $context, $domain );
  88  }
  89  
  90  /**
  91   * Retrieves the translation of $text. If there is no translation, or
  92   * the domain isn't loaded the original text is returned.
  93   *
  94   * @see translate() An alias of translate()
  95   * @since 2.1.0
  96   *
  97   * @param string $text Text to translate
  98   * @param string $domain Optional. Domain to retrieve the translated text
  99   * @return string Translated text
 100   */
 101  function __( $text, $domain = 'default' ) {
 102      return translate( $text, $domain );
 103  }
 104  
 105  /**
 106   * Retrieves the translation of $text and escapes it for safe use in an attribute.
 107   * If there is no translation, or the domain isn't loaded the original text is returned.
 108   *
 109   * @see translate() An alias of translate()
 110   * @see esc_attr()
 111   * @since 2.8.0
 112   *
 113   * @param string $text Text to translate
 114   * @param string $domain Optional. Domain to retrieve the translated text
 115   * @return string Translated text
 116   */
 117  function esc_attr__( $text, $domain = 'default' ) {
 118      return esc_attr( translate( $text, $domain ) );
 119  }
 120  
 121  /**
 122   * Retrieves the translation of $text and escapes it for safe use in HTML output.
 123   * If there is no translation, or the domain isn't loaded the original text is returned.
 124   *
 125   * @see translate() An alias of translate()
 126   * @see esc_html()
 127   * @since 2.8.0
 128   *
 129   * @param string $text Text to translate
 130   * @param string $domain Optional. Domain to retrieve the translated text
 131   * @return string Translated text
 132   */
 133  function esc_html__( $text, $domain = 'default' ) {
 134      return esc_html( translate( $text, $domain ) );
 135  }
 136  
 137  /**
 138   * Displays the returned translated text from translate().
 139   *
 140   * @see translate() Echoes returned translate() string
 141   * @since 1.2.0
 142   *
 143   * @param string $text Text to translate
 144   * @param string $domain Optional. Domain to retrieve the translated text
 145   */
 146  function _e( $text, $domain = 'default' ) {
 147      echo translate( $text, $domain );
 148  }
 149  
 150  /**
 151   * Displays translated text that has been escaped for safe use in an attribute.
 152   *
 153   * @see translate() Echoes returned translate() string
 154   * @see esc_attr()
 155   * @since 2.8.0
 156   *
 157   * @param string $text Text to translate
 158   * @param string $domain Optional. Domain to retrieve the translated text
 159   */
 160  function esc_attr_e( $text, $domain = 'default' ) {
 161      echo esc_attr( translate( $text, $domain ) );
 162  }
 163  
 164  /**
 165   * Displays translated text that has been escaped for safe use in HTML output.
 166   *
 167   * @see translate() Echoes returned translate() string
 168   * @see esc_html()
 169   * @since 2.8.0
 170   *
 171   * @param string $text Text to translate
 172   * @param string $domain Optional. Domain to retrieve the translated text
 173   */
 174  function esc_html_e( $text, $domain = 'default' ) {
 175      echo esc_html( translate( $text, $domain ) );
 176  }
 177  
 178  /**
 179   * Retrieve translated string with gettext context
 180   *
 181   * Quite a few times, there will be collisions with similar translatable text
 182   * found in more than two places but with different translated context.
 183   *
 184   * By including the context in the pot file translators can translate the two
 185   * string differently
 186   *
 187   * @since 2.8
 188   *
 189   * @param string $text Text to translate
 190   * @param string $context Context information for the translators
 191   * @param string $domain Optional. Domain to retrieve the translated text
 192   * @return string Translated context string without pipe
 193   */
 194  
 195  function _x( $single, $context, $domain = 'default' ) {
 196      return translate_with_gettext_context( $single, $context, $domain );
 197  }
 198  
 199  function esc_attr_x( $single, $context, $domain = 'default' ) {
 200      return esc_attr( translate_with_gettext_context( $single, $context, $domain ) );
 201  }
 202  
 203  function esc_html_x( $single, $context, $domain = 'default' ) {
 204      return esc_html( translate_with_gettext_context( $single, $context, $domain ) );
 205  }
 206  
 207  function __ngettext() {
 208      _deprecated_function( __FUNCTION__, '2.8', '_n()' );
 209      $args = func_get_args();
 210      return call_user_func_array('_n', $args);
 211  }
 212  
 213  /**
 214   * Retrieve the plural or single form based on the amount.
 215   *
 216   * If the domain is not set in the $l10n list, then a comparison will be made
 217   * and either $plural or $single parameters returned.
 218   *
 219   * If the domain does exist, then the parameters $single, $plural, and $number
 220   * will first be passed to the domain's ngettext method. Then it will be passed
 221   * to the 'ngettext' filter hook along with the same parameters. The expected
 222   * type will be a string.
 223   *
 224   * @since 1.2.0
 225   * @uses $l10n Gets list of domain translated string (gettext_reader) objects
 226   * @uses apply_filters() Calls 'ngettext' hook on domains text returned,
 227   *        along with $single, $plural, and $number parameters. Expected to return string.
 228   *
 229   * @param string $single The text that will be used if $number is 1
 230   * @param string $plural The text that will be used if $number is not 1
 231   * @param int $number The number to compare against to use either $single or $plural
 232   * @param string $domain Optional. The domain identifier the text should be retrieved in
 233   * @return string Either $single or $plural translated text
 234   */
 235  function _n( $single, $plural, $number, $domain = 'default' ) {
 236      $translations = &get_translations_for_domain( $domain );
 237      $translation = $translations->translate_plural( $single, $plural, $number );
 238      return apply_filters( 'ngettext', $translation, $single, $plural, $number, $domain );
 239  }
 240  
 241  /**
 242   * @see _n() A version of _n(), which supports contexts --
 243   * strips everything from the translation after the last bar
 244   *
 245   */
 246  function _nc( $single, $plural, $number, $domain = 'default' ) {
 247      return before_last_bar( _n( $single, $plural, $number, $domain ) );
 248  }
 249  
 250  function _nx($single, $plural, $number, $context, $domain = 'default') {
 251      $translations = &get_translations_for_domain( $domain );
 252      $translation = $translations->translate_plural( $single, $plural, $number, $context );
 253      return apply_filters( 'ngettext_with_context', $translation, $single, $plural, $number, $context, $domain );
 254  }
 255  
 256  /**
 257   * @deprecated Use _n_noop()
 258   */
 259  function __ngettext_noop() {
 260      _deprecated_function( __FUNCTION__, '2.8', '_n_noop()' );
 261      $args = func_get_args();
 262      return call_user_func_array('_n_noop', $args);
 263  
 264  }
 265  
 266  /**
 267   * Register plural strings in POT file, but don't translate them.
 268   *
 269   * Used when you want do keep structures with translatable plural strings and
 270   * use them later.
 271   *
 272   * Example:
 273   *  $messages = array(
 274   *      'post' => _n_noop('%s post', '%s posts'),
 275   *      'page' => _n_noop('%s pages', '%s pages')
 276   *  );
 277   *  ...
 278   *  $message = $messages[$type];
 279   *  $usable_text = sprintf(_n($message[0], $message[1], $count), $count);
 280   *
 281   * @since 2.5
 282   * @param $single Single form to be i18ned
 283   * @param $plural Plural form to be i18ned
 284   * @return array array($single, $plural)
 285   */
 286  function _n_noop( $single, $plural ) {
 287      return array( $single, $plural );
 288  }
 289  
 290  /**
 291   * Register plural strings with context in POT file, but don't translate them.
 292   *
 293   * @see _n_noop()
 294   */
 295  function _nx_noop( $single, $plural, $context ) {
 296      return array( $single, $plural, $context );
 297  }
 298  
 299  
 300  /**
 301   * Loads a MO file into the domain $domain.
 302   *
 303   * If the domain already exists, the translations will be merged. If both
 304   * sets have the same string, the translation from the original value will be taken.
 305   *
 306   * On success, the .mo file will be placed in the $l10n global by $domain
 307   * and will be a MO object.
 308   *
 309   * @since 1.5.0
 310   * @uses $l10n Gets list of domain translated string objects
 311   *
 312   * @param string $domain Unique identifier for retrieving translated strings
 313   * @param string $mofile Path to the .mo file
 314   * @return bool true on success, false on failure
 315   */
 316  function load_textdomain( $domain, $mofile ) {
 317      global $l10n;
 318      
 319      $plugin_override = apply_filters( 'override_load_textdomain', false, $domain, $mofile );
 320      
 321      if ( true == $plugin_override ) {
 322          return true;
 323      }
 324      
 325      do_action( 'load_textdomain', $domain, $mofile );
 326          
 327      $mofile = apply_filters( 'load_textdomain_mofile', $mofile, $domain );
 328  
 329      if ( !is_readable( $mofile ) ) return false;
 330  
 331      $mo = new MO();
 332      if ( !$mo->import_from_file( $mofile ) ) return false;
 333  
 334      if ( isset( $l10n[$domain] ) )
 335          $mo->merge_with( $l10n[$domain] );
 336  
 337      $l10n[$domain] = &$mo;
 338      
 339      return true;
 340  }
 341  
 342  /**
 343   * Loads default translated strings based on locale.
 344   *
 345   * Loads the .mo file in WP_LANG_DIR constant path from WordPress root. The
 346   * translated (.mo) file is named based off of the locale.
 347   *
 348   * @since 1.5.0
 349   */
 350  function load_default_textdomain() {
 351      $locale = get_locale();
 352  
 353      $mofile = WP_LANG_DIR . "/$locale.mo";
 354  
 355      return load_textdomain( 'default', $mofile );
 356  }
 357  
 358  /**
 359   * Loads the plugin's translated strings.
 360   *
 361   * If the path is not given then it will be the root of the plugin directory.
 362   * The .mo file should be named based on the domain with a dash, and then the locale exactly.
 363   *
 364   * @since 1.5.0
 365   *
 366   * @param string $domain Unique identifier for retrieving translated strings
 367   * @param string $abs_rel_path Optional. Relative path to ABSPATH of a folder,
 368   *     where the .mo file resides. Deprecated, but still functional until 2.7
 369   * @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
 370   */
 371  function load_plugin_textdomain( $domain, $abs_rel_path = false, $plugin_rel_path = false ) {
 372      $locale = get_locale();
 373  
 374      if ( false !== $plugin_rel_path    )
 375          $path = WP_PLUGIN_DIR . '/' . trim( $plugin_rel_path, '/' );
 376      else if ( false !== $abs_rel_path )
 377          $path = ABSPATH . trim( $abs_rel_path, '/' );
 378      else
 379          $path = WP_PLUGIN_DIR;
 380  
 381      $mofile = $path . '/'. $domain . '-' . $locale . '.mo';
 382      return load_textdomain( $domain, $mofile );
 383  }
 384  
 385  /**
 386   * Loads the theme's translated strings.
 387   *
 388   * If the current locale exists as a .mo file in the theme's root directory, it
 389   * will be included in the translated strings by the $domain.
 390   *
 391   * The .mo files must be named based on the locale exactly.
 392   *
 393   * @since 1.5.0
 394   *
 395   * @param string $domain Unique identifier for retrieving translated strings
 396   */
 397  function load_theme_textdomain($domain, $path = false) {
 398      $locale = get_locale();
 399  
 400      $path = ( empty( $path ) ) ? get_template_directory() : $path;
 401  
 402      $mofile = "$path/$locale.mo";
 403      return load_textdomain($domain, $mofile);
 404  }
 405  
 406  /**
 407   * Loads the child themes translated strings.
 408   *
 409   * If the current locale exists as a .mo file in the child themes root directory, it
 410   * will be included in the translated strings by the $domain.
 411   *
 412   * The .mo files must be named based on the locale exactly.
 413   *
 414   * @since 2.9.0
 415   *
 416   * @param string $domain Unique identifier for retrieving translated strings
 417   */
 418  function load_child_theme_textdomain($domain, $path = false) {
 419          $locale = get_locale();
 420  
 421          $path = ( empty( $path ) ) ? get_stylesheet_directory() : $path;
 422  
 423          $mofile = "$path/$locale.mo";
 424          return load_textdomain($domain, $mofile);
 425  }
 426  
 427  /**
 428   * Returns the Translations instance for a domain. If there isn't one,
 429   * returns empty Translations instance.
 430   *
 431   * @param string $domain
 432   * @return object A Translation instance
 433   */
 434  function &get_translations_for_domain( $domain ) {
 435      global $l10n;
 436      if ( !isset( $l10n[$domain] ) ) {
 437          $l10n[$domain] = &new NOOP_Translations;
 438      }
 439      return $l10n[$domain];
 440  }
 441  
 442  /**
 443   * Translates role name. Since the role names are in the database and
 444   * not in the source there are dummy gettext calls to get them into the POT
 445   * file and this function properly translates them back.
 446   *
 447   * The before_last_bar() call is needed, because older installs keep the roles
 448   * using the old context format: 'Role name|User role' and just skipping the
 449   * content after the last bar is easier than fixing them in the DB. New installs
 450   * won't suffer from that problem.
 451   */
 452  function translate_user_role( $name ) {
 453      return translate_with_gettext_context( before_last_bar($name), 'User role' );
 454  }
 455  ?>