| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Core Translation API 4 * 5 * @package WordPress 6 * @subpackage i18n 7 * @since 1.2.0 8 */ 9 10 /** 11 * Retrieves the current locale. 12 * 13 * If the locale is set, then it will filter the locale in the {@see 'locale'} 14 * filter hook and return the value. 15 * 16 * If the locale is not set already, then the WPLANG constant is used if it is 17 * defined. Then it is filtered through the {@see 'locale'} filter hook and 18 * the value for the locale global set and the locale is returned. 19 * 20 * The process to get the locale should only be done once, but the locale will 21 * always be filtered using the {@see 'locale'} hook. 22 * 23 * @since 1.5.0 24 * 25 * @global string $locale 26 * @global string $wp_local_package 27 * 28 * @return string The locale of the blog or from the {@see 'locale'} hook. 29 */ 30 function get_locale() { 31 global $locale, $wp_local_package; 32 33 if ( isset( $locale ) ) { 34 /** 35 * Filters the locale ID of the WordPress installation. 36 * 37 * @since 1.5.0 38 * 39 * @param string $locale The locale ID. 40 */ 41 return apply_filters( 'locale', $locale ); 42 } 43 44 if ( isset( $wp_local_package ) ) { 45 $locale = $wp_local_package; 46 } 47 48 // WPLANG was defined in wp-config. 49 if ( defined( 'WPLANG' ) ) { 50 $locale = WPLANG; 51 } 52 53 // If multisite, check options. 54 if ( is_multisite() ) { 55 // Don't check blog option when installing. 56 if ( wp_installing() ) { 57 $ms_locale = get_site_option( 'WPLANG' ); 58 } else { 59 $ms_locale = get_option( 'WPLANG' ); 60 if ( false === $ms_locale ) { 61 $ms_locale = get_site_option( 'WPLANG' ); 62 } 63 } 64 65 if ( $ms_locale !== false ) { 66 $locale = $ms_locale; 67 } 68 } else { 69 $db_locale = get_option( 'WPLANG' ); 70 if ( $db_locale !== false ) { 71 $locale = $db_locale; 72 } 73 } 74 75 if ( empty( $locale ) ) { 76 $locale = 'en_US'; 77 } 78 79 /** This filter is documented in wp-includes/l10n.php */ 80 return apply_filters( 'locale', $locale ); 81 } 82 83 /** 84 * Retrieves the locale of a user. 85 * 86 * If the user has a locale set to a non-empty string then it will be 87 * returned. Otherwise it returns the locale of get_locale(). 88 * 89 * @since 4.7.0 90 * 91 * @param int|WP_User $user_id User's ID or a WP_User object. Defaults to current user. 92 * @return string The locale of the user. 93 */ 94 function get_user_locale( $user_id = 0 ) { 95 $user = false; 96 if ( 0 === $user_id && function_exists( 'wp_get_current_user' ) ) { 97 $user = wp_get_current_user(); 98 } elseif ( $user_id instanceof WP_User ) { 99 $user = $user_id; 100 } elseif ( $user_id && is_numeric( $user_id ) ) { 101 $user = get_user_by( 'id', $user_id ); 102 } 103 104 if ( ! $user ) { 105 return get_locale(); 106 } 107 108 $locale = $user->locale; 109 return $locale ? $locale : get_locale(); 110 } 111 112 /** 113 * Determine the current locale desired for the request. 114 * 115 * @since 5.0.0 116 * 117 * @global string $pagenow 118 * 119 * @return string The determined locale. 120 */ 121 function determine_locale() { 122 /** 123 * Filters the locale for the current request prior to the default determination process. 124 * 125 * Using this filter allows to override the default logic, effectively short-circuiting the function. 126 * 127 * @since 5.0.0 128 * 129 * @param string|null $locale The locale to return and short-circuit. Default null. 130 */ 131 $determined_locale = apply_filters( 'pre_determine_locale', null ); 132 if ( ! empty( $determined_locale ) && is_string( $determined_locale ) ) { 133 return $determined_locale; 134 } 135 136 $determined_locale = get_locale(); 137 138 if ( is_admin() ) { 139 $determined_locale = get_user_locale(); 140 } 141 142 if ( isset( $_GET['_locale'] ) && 'user' === $_GET['_locale'] && wp_is_json_request() ) { 143 $determined_locale = get_user_locale(); 144 } 145 146 if ( ! empty( $_GET['wp_lang'] ) && ! empty( $GLOBALS['pagenow'] ) && 'wp-login.php' === $GLOBALS['pagenow'] ) { 147 $determined_locale = sanitize_text_field( $_GET['wp_lang'] ); 148 } 149 150 /** 151 * Filters the locale for the current request. 152 * 153 * @since 5.0.0 154 * 155 * @param string $locale The locale. 156 */ 157 return apply_filters( 'determine_locale', $determined_locale ); 158 } 159 160 /** 161 * Retrieve the translation of $text. 162 * 163 * If there is no translation, or the text domain isn't loaded, the original text is returned. 164 * 165 * *Note:* Don't use translate() directly, use __() or related functions. 166 * 167 * @since 2.2.0 168 * 169 * @param string $text Text to translate. 170 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 171 * Default 'default'. 172 * @return string Translated text. 173 */ 174 function translate( $text, $domain = 'default' ) { 175 $translations = get_translations_for_domain( $domain ); 176 $translation = $translations->translate( $text ); 177 178 /** 179 * Filters text with its translation. 180 * 181 * @since 2.0.11 182 * 183 * @param string $translation Translated text. 184 * @param string $text Text to translate. 185 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 186 */ 187 return apply_filters( 'gettext', $translation, $text, $domain ); 188 } 189 190 /** 191 * Remove last item on a pipe-delimited string. 192 * 193 * Meant for removing the last item in a string, such as 'Role name|User role'. The original 194 * string will be returned if no pipe '|' characters are found in the string. 195 * 196 * @since 2.8.0 197 * 198 * @param string $string A pipe-delimited string. 199 * @return string Either $string or everything before the last pipe. 200 */ 201 function before_last_bar( $string ) { 202 $last_bar = strrpos( $string, '|' ); 203 if ( false === $last_bar ) { 204 return $string; 205 } else { 206 return substr( $string, 0, $last_bar ); 207 } 208 } 209 210 /** 211 * Retrieve the translation of $text in the context defined in $context. 212 * 213 * If there is no translation, or the text domain isn't loaded, the original text is returned. 214 * 215 * *Note:* Don't use translate_with_gettext_context() directly, use _x() or related functions. 216 * 217 * @since 2.8.0 218 * 219 * @param string $text Text to translate. 220 * @param string $context Context information for the translators. 221 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 222 * Default 'default'. 223 * @return string Translated text on success, original text on failure. 224 */ 225 function translate_with_gettext_context( $text, $context, $domain = 'default' ) { 226 $translations = get_translations_for_domain( $domain ); 227 $translation = $translations->translate( $text, $context ); 228 /** 229 * Filters text with its translation based on context information. 230 * 231 * @since 2.8.0 232 * 233 * @param string $translation Translated text. 234 * @param string $text Text to translate. 235 * @param string $context Context information for the translators. 236 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 237 */ 238 return apply_filters( 'gettext_with_context', $translation, $text, $context, $domain ); 239 } 240 241 /** 242 * Retrieve the translation of $text. 243 * 244 * If there is no translation, or the text domain isn't loaded, the original text is returned. 245 * 246 * @since 2.1.0 247 * 248 * @param string $text Text to translate. 249 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 250 * Default 'default'. 251 * @return string Translated text. 252 */ 253 function __( $text, $domain = 'default' ) { 254 return translate( $text, $domain ); 255 } 256 257 /** 258 * Retrieve the translation of $text and escapes it for safe use in an attribute. 259 * 260 * If there is no translation, or the text domain isn't loaded, the original text is returned. 261 * 262 * @since 2.8.0 263 * 264 * @param string $text Text to translate. 265 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 266 * Default 'default'. 267 * @return string Translated text on success, original text on failure. 268 */ 269 function esc_attr__( $text, $domain = 'default' ) { 270 return esc_attr( translate( $text, $domain ) ); 271 } 272 273 /** 274 * Retrieve the translation of $text and escapes it for safe use in HTML output. 275 * 276 * If there is no translation, or the text domain isn't loaded, the original text 277 * is escaped and returned. 278 * 279 * @since 2.8.0 280 * 281 * @param string $text Text to translate. 282 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 283 * Default 'default'. 284 * @return string Translated text. 285 */ 286 function esc_html__( $text, $domain = 'default' ) { 287 return esc_html( translate( $text, $domain ) ); 288 } 289 290 /** 291 * Display translated text. 292 * 293 * @since 1.2.0 294 * 295 * @param string $text Text to translate. 296 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 297 * Default 'default'. 298 */ 299 function _e( $text, $domain = 'default' ) { 300 echo translate( $text, $domain ); 301 } 302 303 /** 304 * Display translated text that has been escaped for safe use in an attribute. 305 * 306 * Encodes `< > & " '` (less than, greater than, ampersand, double quote, single quote). 307 * Will never double encode entities. 308 * 309 * If you need the value for use in PHP, use esc_attr__(). 310 * 311 * @since 2.8.0 312 * 313 * @param string $text Text to translate. 314 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 315 * Default 'default'. 316 */ 317 function esc_attr_e( $text, $domain = 'default' ) { 318 echo esc_attr( translate( $text, $domain ) ); 319 } 320 321 /** 322 * Display translated text that has been escaped for safe use in HTML output. 323 * 324 * If there is no translation, or the text domain isn't loaded, the original text 325 * is escaped and displayed. 326 * 327 * If you need the value for use in PHP, use esc_html__(). 328 * 329 * @since 2.8.0 330 * 331 * @param string $text Text to translate. 332 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 333 * Default 'default'. 334 */ 335 function esc_html_e( $text, $domain = 'default' ) { 336 echo esc_html( translate( $text, $domain ) ); 337 } 338 339 /** 340 * Retrieve translated string with gettext context. 341 * 342 * Quite a few times, there will be collisions with similar translatable text 343 * found in more than two places, but with different translated context. 344 * 345 * By including the context in the pot file, translators can translate the two 346 * strings differently. 347 * 348 * @since 2.8.0 349 * 350 * @param string $text Text to translate. 351 * @param string $context Context information for the translators. 352 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 353 * Default 'default'. 354 * @return string Translated context string without pipe. 355 */ 356 function _x( $text, $context, $domain = 'default' ) { 357 return translate_with_gettext_context( $text, $context, $domain ); 358 } 359 360 /** 361 * Display translated string with gettext context. 362 * 363 * @since 3.0.0 364 * 365 * @param string $text Text to translate. 366 * @param string $context Context information for the translators. 367 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 368 * Default 'default'. 369 * @return string Translated context string without pipe. 370 */ 371 function _ex( $text, $context, $domain = 'default' ) { 372 echo _x( $text, $context, $domain ); 373 } 374 375 /** 376 * Translate string with gettext context, and escapes it for safe use in an attribute. 377 * 378 * If there is no translation, or the text domain isn't loaded, the original text 379 * is escaped and returned. 380 * 381 * @since 2.8.0 382 * 383 * @param string $text Text to translate. 384 * @param string $context Context information for the translators. 385 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 386 * Default 'default'. 387 * @return string Translated text. 388 */ 389 function esc_attr_x( $text, $context, $domain = 'default' ) { 390 return esc_attr( translate_with_gettext_context( $text, $context, $domain ) ); 391 } 392 393 /** 394 * Translate string with gettext context, and escapes it for safe use in HTML output. 395 * 396 * If there is no translation, or the text domain isn't loaded, the original text 397 * is escaped and returned. 398 * 399 * @since 2.9.0 400 * 401 * @param string $text Text to translate. 402 * @param string $context Context information for the translators. 403 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 404 * Default 'default'. 405 * @return string Translated text. 406 */ 407 function esc_html_x( $text, $context, $domain = 'default' ) { 408 return esc_html( translate_with_gettext_context( $text, $context, $domain ) ); 409 } 410 411 /** 412 * Translates and retrieves the singular or plural form based on the supplied number. 413 * 414 * Used when you want to use the appropriate form of a string based on whether a 415 * number is singular or plural. 416 * 417 * Example: 418 * 419 * printf( _n( '%s person', '%s people', $count, 'text-domain' ), number_format_i18n( $count ) ); 420 * 421 * @since 2.8.0 422 * 423 * @param string $single The text to be used if the number is singular. 424 * @param string $plural The text to be used if the number is plural. 425 * @param int $number The number to compare against to use either the singular or plural form. 426 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 427 * Default 'default'. 428 * @return string The translated singular or plural form. 429 */ 430 function _n( $single, $plural, $number, $domain = 'default' ) { 431 $translations = get_translations_for_domain( $domain ); 432 $translation = $translations->translate_plural( $single, $plural, $number ); 433 434 /** 435 * Filters the singular or plural form of a string. 436 * 437 * @since 2.2.0 438 * 439 * @param string $translation Translated text. 440 * @param string $single The text to be used if the number is singular. 441 * @param string $plural The text to be used if the number is plural. 442 * @param string $number The number to compare against to use either the singular or plural form. 443 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 444 */ 445 return apply_filters( 'ngettext', $translation, $single, $plural, $number, $domain ); 446 } 447 448 /** 449 * Translates and retrieves the singular or plural form based on the supplied number, with gettext context. 450 * 451 * This is a hybrid of _n() and _x(). It supports context and plurals. 452 * 453 * Used when you want to use the appropriate form of a string with context based on whether a 454 * number is singular or plural. 455 * 456 * Example of a generic phrase which is disambiguated via the context parameter: 457 * 458 * printf( _nx( '%s group', '%s groups', $people, 'group of people', 'text-domain' ), number_format_i18n( $people ) ); 459 * printf( _nx( '%s group', '%s groups', $animals, 'group of animals', 'text-domain' ), number_format_i18n( $animals ) ); 460 * 461 * @since 2.8.0 462 * 463 * @param string $single The text to be used if the number is singular. 464 * @param string $plural The text to be used if the number is plural. 465 * @param int $number The number to compare against to use either the singular or plural form. 466 * @param string $context Context information for the translators. 467 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 468 * Default 'default'. 469 * @return string The translated singular or plural form. 470 */ 471 function _nx( $single, $plural, $number, $context, $domain = 'default' ) { 472 $translations = get_translations_for_domain( $domain ); 473 $translation = $translations->translate_plural( $single, $plural, $number, $context ); 474 475 /** 476 * Filters the singular or plural form of a string with gettext context. 477 * 478 * @since 2.8.0 479 * 480 * @param string $translation Translated text. 481 * @param string $single The text to be used if the number is singular. 482 * @param string $plural The text to be used if the number is plural. 483 * @param string $number The number to compare against to use either the singular or plural form. 484 * @param string $context Context information for the translators. 485 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 486 */ 487 return apply_filters( 'ngettext_with_context', $translation, $single, $plural, $number, $context, $domain ); 488 } 489 490 /** 491 * Registers plural strings in POT file, but does not translate them. 492 * 493 * Used when you want to keep structures with translatable plural 494 * strings and use them later when the number is known. 495 * 496 * Example: 497 * 498 * $message = _n_noop( '%s post', '%s posts', 'text-domain' ); 499 * ... 500 * printf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) ); 501 * 502 * @since 2.5.0 503 * 504 * @param string $singular Singular form to be localized. 505 * @param string $plural Plural form to be localized. 506 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 507 * Default null. 508 * @return array { 509 * Array of translation information for the strings. 510 * 511 * @type string $0 Singular form to be localized. No longer used. 512 * @type string $1 Plural form to be localized. No longer used. 513 * @type string $singular Singular form to be localized. 514 * @type string $plural Plural form to be localized. 515 * @type null $context Context information for the translators. 516 * @type string $domain Text domain. 517 * } 518 */ 519 function _n_noop( $singular, $plural, $domain = null ) { 520 return array( 521 0 => $singular, 522 1 => $plural, 523 'singular' => $singular, 524 'plural' => $plural, 525 'context' => null, 526 'domain' => $domain, 527 ); 528 } 529 530 /** 531 * Registers plural strings with gettext context in POT file, but does not translate them. 532 * 533 * Used when you want to keep structures with translatable plural 534 * strings and use them later when the number is known. 535 * 536 * Example of a generic phrase which is disambiguated via the context parameter: 537 * 538 * $messages = array( 539 * 'people' => _nx_noop( '%s group', '%s groups', 'people', 'text-domain' ), 540 * 'animals' => _nx_noop( '%s group', '%s groups', 'animals', 'text-domain' ), 541 * ); 542 * ... 543 * $message = $messages[ $type ]; 544 * printf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) ); 545 * 546 * @since 2.8.0 547 * 548 * @param string $singular Singular form to be localized. 549 * @param string $plural Plural form to be localized. 550 * @param string $context Context information for the translators. 551 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 552 * Default null. 553 * @return array { 554 * Array of translation information for the strings. 555 * 556 * @type string $0 Singular form to be localized. No longer used. 557 * @type string $1 Plural form to be localized. No longer used. 558 * @type string $2 Context information for the translators. No longer used. 559 * @type string $singular Singular form to be localized. 560 * @type string $plural Plural form to be localized. 561 * @type string $context Context information for the translators. 562 * @type string $domain Text domain. 563 * } 564 */ 565 function _nx_noop( $singular, $plural, $context, $domain = null ) { 566 return array( 567 0 => $singular, 568 1 => $plural, 569 2 => $context, 570 'singular' => $singular, 571 'plural' => $plural, 572 'context' => $context, 573 'domain' => $domain, 574 ); 575 } 576 577 /** 578 * Translates and retrieves the singular or plural form of a string that's been registered 579 * with _n_noop() or _nx_noop(). 580 * 581 * Used when you want to use a translatable plural string once the number is known. 582 * 583 * Example: 584 * 585 * $message = _n_noop( '%s post', '%s posts', 'text-domain' ); 586 * ... 587 * printf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) ); 588 * 589 * @since 3.1.0 590 * 591 * @param array $nooped_plural Array with singular, plural, and context keys, usually the result of _n_noop() or _nx_noop(). 592 * @param int $count Number of objects. 593 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. If $nooped_plural contains 594 * a text domain passed to _n_noop() or _nx_noop(), it will override this value. Default 'default'. 595 * @return string Either $single or $plural translated text. 596 */ 597 function translate_nooped_plural( $nooped_plural, $count, $domain = 'default' ) { 598 if ( $nooped_plural['domain'] ) { 599 $domain = $nooped_plural['domain']; 600 } 601 602 if ( $nooped_plural['context'] ) { 603 return _nx( $nooped_plural['singular'], $nooped_plural['plural'], $count, $nooped_plural['context'], $domain ); 604 } else { 605 return _n( $nooped_plural['singular'], $nooped_plural['plural'], $count, $domain ); 606 } 607 } 608 609 /** 610 * Load a .mo file into the text domain $domain. 611 * 612 * If the text domain already exists, the translations will be merged. If both 613 * sets have the same string, the translation from the original value will be taken. 614 * 615 * On success, the .mo file will be placed in the $l10n global by $domain 616 * and will be a MO object. 617 * 618 * @since 1.5.0 619 * 620 * @global MO[] $l10n An array of all currently loaded text domains. 621 * @global MO[] $l10n_unloaded An array of all text domains that have been unloaded again. 622 * 623 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 624 * @param string $mofile Path to the .mo file. 625 * @return bool True on success, false on failure. 626 */ 627 function load_textdomain( $domain, $mofile ) { 628 global $l10n, $l10n_unloaded; 629 630 $l10n_unloaded = (array) $l10n_unloaded; 631 632 /** 633 * Filters whether to override the .mo file loading. 634 * 635 * @since 2.9.0 636 * 637 * @param bool $override Whether to override the .mo file loading. Default false. 638 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 639 * @param string $mofile Path to the MO file. 640 */ 641 $plugin_override = apply_filters( 'override_load_textdomain', false, $domain, $mofile ); 642 643 if ( true == $plugin_override ) { 644 unset( $l10n_unloaded[ $domain ] ); 645 646 return true; 647 } 648 649 /** 650 * Fires before the MO translation file is loaded. 651 * 652 * @since 2.9.0 653 * 654 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 655 * @param string $mofile Path to the .mo file. 656 */ 657 do_action( 'load_textdomain', $domain, $mofile ); 658 659 /** 660 * Filters MO file path for loading translations for a specific text domain. 661 * 662 * @since 2.9.0 663 * 664 * @param string $mofile Path to the MO file. 665 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 666 */ 667 $mofile = apply_filters( 'load_textdomain_mofile', $mofile, $domain ); 668 669 if ( ! is_readable( $mofile ) ) { 670 return false; 671 } 672 673 $mo = new MO(); 674 if ( ! $mo->import_from_file( $mofile ) ) { 675 return false; 676 } 677 678 if ( isset( $l10n[ $domain ] ) ) { 679 $mo->merge_with( $l10n[ $domain ] ); 680 } 681 682 unset( $l10n_unloaded[ $domain ] ); 683 684 $l10n[ $domain ] = &$mo; 685 686 return true; 687 } 688 689 /** 690 * Unload translations for a text domain. 691 * 692 * @since 3.0.0 693 * 694 * @global MO[] $l10n An array of all currently loaded text domains. 695 * @global MO[] $l10n_unloaded An array of all text domains that have been unloaded again. 696 * 697 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 698 * @return bool Whether textdomain was unloaded. 699 */ 700 function unload_textdomain( $domain ) { 701 global $l10n, $l10n_unloaded; 702 703 $l10n_unloaded = (array) $l10n_unloaded; 704 705 /** 706 * Filters whether to override the text domain unloading. 707 * 708 * @since 3.0.0 709 * 710 * @param bool $override Whether to override the text domain unloading. Default false. 711 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 712 */ 713 $plugin_override = apply_filters( 'override_unload_textdomain', false, $domain ); 714 715 if ( $plugin_override ) { 716 $l10n_unloaded[ $domain ] = true; 717 718 return true; 719 } 720 721 /** 722 * Fires before the text domain is unloaded. 723 * 724 * @since 3.0.0 725 * 726 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 727 */ 728 do_action( 'unload_textdomain', $domain ); 729 730 if ( isset( $l10n[ $domain ] ) ) { 731 unset( $l10n[ $domain ] ); 732 733 $l10n_unloaded[ $domain ] = true; 734 735 return true; 736 } 737 738 return false; 739 } 740 741 /** 742 * Load default translated strings based on locale. 743 * 744 * Loads the .mo file in WP_LANG_DIR constant path from WordPress root. 745 * The translated (.mo) file is named based on the locale. 746 * 747 * @see load_textdomain() 748 * 749 * @since 1.5.0 750 * 751 * @param string $locale Optional. Locale to load. Default is the value of get_locale(). 752 * @return bool Whether the textdomain was loaded. 753 */ 754 function load_default_textdomain( $locale = null ) { 755 if ( null === $locale ) { 756 $locale = determine_locale(); 757 } 758 759 // Unload previously loaded strings so we can switch translations. 760 unload_textdomain( 'default' ); 761 762 $return = load_textdomain( 'default', WP_LANG_DIR . "/$locale.mo" ); 763 764 if ( ( is_multisite() || ( defined( 'WP_INSTALLING_NETWORK' ) && WP_INSTALLING_NETWORK ) ) && ! file_exists( WP_LANG_DIR . "/admin-$locale.mo" ) ) { 765 load_textdomain( 'default', WP_LANG_DIR . "/ms-$locale.mo" ); 766 return $return; 767 } 768 769 if ( is_admin() || wp_installing() || ( defined( 'WP_REPAIRING' ) && WP_REPAIRING ) ) { 770 load_textdomain( 'default', WP_LANG_DIR . "/admin-$locale.mo" ); 771 } 772 773 if ( is_network_admin() || ( defined( 'WP_INSTALLING_NETWORK' ) && WP_INSTALLING_NETWORK ) ) { 774 load_textdomain( 'default', WP_LANG_DIR . "/admin-network-$locale.mo" ); 775 } 776 777 return $return; 778 } 779 780 /** 781 * Loads a plugin's translated strings. 782 * 783 * If the path is not given then it will be the root of the plugin directory. 784 * 785 * The .mo file should be named based on the text domain with a dash, and then the locale exactly. 786 * 787 * @since 1.5.0 788 * @since 4.6.0 The function now tries to load the .mo file from the languages directory first. 789 * 790 * @param string $domain Unique identifier for retrieving translated strings 791 * @param string|false $deprecated Optional. Deprecated. Use the $plugin_rel_path parameter instead. 792 * Default false. 793 * @param string|false $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR where the .mo file resides. 794 * Default false. 795 * @return bool True when textdomain is successfully loaded, false otherwise. 796 */ 797 function load_plugin_textdomain( $domain, $deprecated = false, $plugin_rel_path = false ) { 798 /** 799 * Filters a plugin's locale. 800 * 801 * @since 3.0.0 802 * 803 * @param string $locale The plugin's current locale. 804 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 805 */ 806 $locale = apply_filters( 'plugin_locale', determine_locale(), $domain ); 807 808 $mofile = $domain . '-' . $locale . '.mo'; 809 810 // Try to load from the languages directory first. 811 if ( load_textdomain( $domain, WP_LANG_DIR . '/plugins/' . $mofile ) ) { 812 return true; 813 } 814 815 if ( false !== $plugin_rel_path ) { 816 $path = WP_PLUGIN_DIR . '/' . trim( $plugin_rel_path, '/' ); 817 } elseif ( false !== $deprecated ) { 818 _deprecated_argument( __FUNCTION__, '2.7.0' ); 819 $path = ABSPATH . trim( $deprecated, '/' ); 820 } else { 821 $path = WP_PLUGIN_DIR; 822 } 823 824 return load_textdomain( $domain, $path . '/' . $mofile ); 825 } 826 827 /** 828 * Load the translated strings for a plugin residing in the mu-plugins directory. 829 * 830 * @since 3.0.0 831 * @since 4.6.0 The function now tries to load the .mo file from the languages directory first. 832 * 833 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 834 * @param string $mu_plugin_rel_path Optional. Relative to `WPMU_PLUGIN_DIR` directory in which the .mo 835 * file resides. Default empty string. 836 * @return bool True when textdomain is successfully loaded, false otherwise. 837 */ 838 function load_muplugin_textdomain( $domain, $mu_plugin_rel_path = '' ) { 839 /** This filter is documented in wp-includes/l10n.php */ 840 $locale = apply_filters( 'plugin_locale', determine_locale(), $domain ); 841 842 $mofile = $domain . '-' . $locale . '.mo'; 843 844 // Try to load from the languages directory first. 845 if ( load_textdomain( $domain, WP_LANG_DIR . '/plugins/' . $mofile ) ) { 846 return true; 847 } 848 849 $path = WPMU_PLUGIN_DIR . '/' . ltrim( $mu_plugin_rel_path, '/' ); 850 851 return load_textdomain( $domain, $path . '/' . $mofile ); 852 } 853 854 /** 855 * Load the theme's translated strings. 856 * 857 * If the current locale exists as a .mo file in the theme's root directory, it 858 * will be included in the translated strings by the $domain. 859 * 860 * The .mo files must be named based on the locale exactly. 861 * 862 * @since 1.5.0 863 * @since 4.6.0 The function now tries to load the .mo file from the languages directory first. 864 * 865 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 866 * @param string $path Optional. Path to the directory containing the .mo file. 867 * Default false. 868 * @return bool True when textdomain is successfully loaded, false otherwise. 869 */ 870 function load_theme_textdomain( $domain, $path = false ) { 871 /** 872 * Filters a theme's locale. 873 * 874 * @since 3.0.0 875 * 876 * @param string $locale The theme's current locale. 877 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 878 */ 879 $locale = apply_filters( 'theme_locale', determine_locale(), $domain ); 880 881 $mofile = $domain . '-' . $locale . '.mo'; 882 883 // Try to load from the languages directory first. 884 if ( load_textdomain( $domain, WP_LANG_DIR . '/themes/' . $mofile ) ) { 885 return true; 886 } 887 888 if ( ! $path ) { 889 $path = get_template_directory(); 890 } 891 892 return load_textdomain( $domain, $path . '/' . $locale . '.mo' ); 893 } 894 895 /** 896 * Load the child themes translated strings. 897 * 898 * If the current locale exists as a .mo file in the child themes 899 * root directory, it will be included in the translated strings by the $domain. 900 * 901 * The .mo files must be named based on the locale exactly. 902 * 903 * @since 2.9.0 904 * 905 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 906 * @param string $path Optional. Path to the directory containing the .mo file. 907 * Default false. 908 * @return bool True when the theme textdomain is successfully loaded, false otherwise. 909 */ 910 function load_child_theme_textdomain( $domain, $path = false ) { 911 if ( ! $path ) { 912 $path = get_stylesheet_directory(); 913 } 914 return load_theme_textdomain( $domain, $path ); 915 } 916 917 /** 918 * Loads the script translated strings. 919 * 920 * @since 5.0.0 921 * @since 5.0.2 Uses load_script_translations() to load translation data. 922 * @since 5.1.0 The `$domain` parameter was made optional. 923 * 924 * @see WP_Scripts::set_translations() 925 * 926 * @param string $handle Name of the script to register a translation domain to. 927 * @param string $domain Optional. Text domain. Default 'default'. 928 * @param string $path Optional. The full file path to the directory containing translation files. 929 * 930 * @return false|string False if the script textdomain could not be loaded, the translated strings 931 * in JSON encoding otherwise. 932 */ 933 function load_script_textdomain( $handle, $domain = 'default', $path = null ) { 934 $wp_scripts = wp_scripts(); 935 936 if ( ! isset( $wp_scripts->registered[ $handle ] ) ) { 937 return false; 938 } 939 940 $path = untrailingslashit( $path ); 941 $locale = determine_locale(); 942 943 // If a path was given and the handle file exists simply return it. 944 $file_base = $domain === 'default' ? $locale : $domain . '-' . $locale; 945 $handle_filename = $file_base . '-' . $handle . '.json'; 946 947 if ( $path ) { 948 $translations = load_script_translations( $path . '/' . $handle_filename, $handle, $domain ); 949 950 if ( $translations ) { 951 return $translations; 952 } 953 } 954 955 $src = $wp_scripts->registered[ $handle ]->src; 956 957 if ( ! preg_match( '|^(https?:)?//|', $src ) && ! ( $wp_scripts->content_url && 0 === strpos( $src, $wp_scripts->content_url ) ) ) { 958 $src = $wp_scripts->base_url . $src; 959 } 960 961 $relative = false; 962 $languages_path = WP_LANG_DIR; 963 964 $src_url = wp_parse_url( $src ); 965 $content_url = wp_parse_url( content_url() ); 966 $plugins_url = wp_parse_url( plugins_url() ); 967 $site_url = wp_parse_url( site_url() ); 968 969 // If the host is the same or it's a relative URL. 970 if ( 971 ( ! isset( $content_url['path'] ) || strpos( $src_url['path'], $content_url['path'] ) === 0 ) && 972 ( ! isset( $src_url['host'] ) || $src_url['host'] === $content_url['host'] ) 973 ) { 974 // Make the src relative the specific plugin or theme. 975 if ( isset( $content_url['path'] ) ) { 976 $relative = substr( $src_url['path'], strlen( $content_url['path'] ) ); 977 } else { 978 $relative = $src_url['path']; 979 } 980 $relative = trim( $relative, '/' ); 981 $relative = explode( '/', $relative ); 982 983 $languages_path = WP_LANG_DIR . '/' . $relative[0]; 984 985 $relative = array_slice( $relative, 2 ); // Remove plugins/<plugin name> or themes/<theme name>. 986 $relative = implode( '/', $relative ); 987 } elseif ( 988 ( ! isset( $plugins_url['path'] ) || strpos( $src_url['path'], $plugins_url['path'] ) === 0 ) && 989 ( ! isset( $src_url['host'] ) || $src_url['host'] === $plugins_url['host'] ) 990 ) { 991 // Make the src relative the specific plugin. 992 if ( isset( $plugins_url['path'] ) ) { 993 $relative = substr( $src_url['path'], strlen( $plugins_url['path'] ) ); 994 } else { 995 $relative = $src_url['path']; 996 } 997 $relative = trim( $relative, '/' ); 998 $relative = explode( '/', $relative ); 999 1000 $languages_path = WP_LANG_DIR . '/plugins'; 1001 1002 $relative = array_slice( $relative, 1 ); // Remove <plugin name>. 1003 $relative = implode( '/', $relative ); 1004 } elseif ( ! isset( $src_url['host'] ) || $src_url['host'] === $site_url['host'] ) { 1005 if ( ! isset( $site_url['path'] ) ) { 1006 $relative = trim( $src_url['path'], '/' ); 1007 } elseif ( ( strpos( $src_url['path'], trailingslashit( $site_url['path'] ) ) === 0 ) ) { 1008 // Make the src relative to the WP root. 1009 $relative = substr( $src_url['path'], strlen( $site_url['path'] ) ); 1010 $relative = trim( $relative, '/' ); 1011 } 1012 } 1013 1014 /** 1015 * Filters the relative path of scripts used for finding translation files. 1016 * 1017 * @since 5.0.2 1018 * 1019 * @param string $relative The relative path of the script. False if it could not be determined. 1020 * @param string $src The full source url of the script. 1021 */ 1022 $relative = apply_filters( 'load_script_textdomain_relative_path', $relative, $src ); 1023 1024 // If the source is not from WP. 1025 if ( false === $relative ) { 1026 return load_script_translations( false, $handle, $domain ); 1027 } 1028 1029 // Translations are always based on the unminified filename. 1030 if ( substr( $relative, -7 ) === '.min.js' ) { 1031 $relative = substr( $relative, 0, -7 ) . '.js'; 1032 } 1033 1034 $md5_filename = $file_base . '-' . md5( $relative ) . '.json'; 1035 1036 if ( $path ) { 1037 $translations = load_script_translations( $path . '/' . $md5_filename, $handle, $domain ); 1038 1039 if ( $translations ) { 1040 return $translations; 1041 } 1042 } 1043 1044 $translations = load_script_translations( $languages_path . '/' . $md5_filename, $handle, $domain ); 1045 1046 if ( $translations ) { 1047 return $translations; 1048 } 1049 1050 return load_script_translations( false, $handle, $domain ); 1051 } 1052 1053 /** 1054 * Loads the translation data for the given script handle and text domain. 1055 * 1056 * @since 5.0.2 1057 * 1058 * @param string|false $file Path to the translation file to load. False if there isn't one. 1059 * @param string $handle Name of the script to register a translation domain to. 1060 * @param string $domain The text domain. 1061 * @return string|false The JSON-encoded translated strings for the given script handle and text domain. False if there are none. 1062 */ 1063 function load_script_translations( $file, $handle, $domain ) { 1064 /** 1065 * Pre-filters script translations for the given file, script handle and text domain. 1066 * 1067 * Returning a non-null value allows to override the default logic, effectively short-circuiting the function. 1068 * 1069 * @since 5.0.2 1070 * 1071 * @param string|false|null $translations JSON-encoded translation data. Default null. 1072 * @param string|false $file Path to the translation file to load. False if there isn't one. 1073 * @param string $handle Name of the script to register a translation domain to. 1074 * @param string $domain The text domain. 1075 */ 1076 $translations = apply_filters( 'pre_load_script_translations', null, $file, $handle, $domain ); 1077 1078 if ( null !== $translations ) { 1079 return $translations; 1080 } 1081 1082 /** 1083 * Filters the file path for loading script translations for the given script handle and text domain. 1084 * 1085 * @since 5.0.2 1086 * 1087 * @param string|false $file Path to the translation file to load. False if there isn't one. 1088 * @param string $handle Name of the script to register a translation domain to. 1089 * @param string $domain The text domain. 1090 */ 1091 $file = apply_filters( 'load_script_translation_file', $file, $handle, $domain ); 1092 1093 if ( ! $file || ! is_readable( $file ) ) { 1094 return false; 1095 } 1096 1097 $translations = file_get_contents( $file ); 1098 1099 /** 1100 * Filters script translations for the given file, script handle and text domain. 1101 * 1102 * @since 5.0.2 1103 * 1104 * @param string $translations JSON-encoded translation data. 1105 * @param string $file Path to the translation file that was loaded. 1106 * @param string $handle Name of the script to register a translation domain to. 1107 * @param string $domain The text domain. 1108 */ 1109 return apply_filters( 'load_script_translations', $translations, $file, $handle, $domain ); 1110 } 1111 1112 /** 1113 * Loads plugin and theme textdomains just-in-time. 1114 * 1115 * When a textdomain is encountered for the first time, we try to load 1116 * the translation file from `wp-content/languages`, removing the need 1117 * to call load_plugin_texdomain() or load_theme_texdomain(). 1118 * 1119 * @since 4.6.0 1120 * @access private 1121 * 1122 * @see get_translations_for_domain() 1123 * @global MO[] $l10n_unloaded An array of all text domains that have been unloaded again. 1124 * 1125 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 1126 * @return bool True when the textdomain is successfully loaded, false otherwise. 1127 */ 1128 function _load_textdomain_just_in_time( $domain ) { 1129 global $l10n_unloaded; 1130 1131 $l10n_unloaded = (array) $l10n_unloaded; 1132 1133 // Short-circuit if domain is 'default' which is reserved for core. 1134 if ( 'default' === $domain || isset( $l10n_unloaded[ $domain ] ) ) { 1135 return false; 1136 } 1137 1138 $translation_path = _get_path_to_translation( $domain ); 1139 if ( false === $translation_path ) { 1140 return false; 1141 } 1142 1143 return load_textdomain( $domain, $translation_path ); 1144 } 1145 1146 /** 1147 * Gets the path to a translation file for loading a textdomain just in time. 1148 * 1149 * Caches the retrieved results internally. 1150 * 1151 * @since 4.7.0 1152 * @access private 1153 * 1154 * @see _load_textdomain_just_in_time() 1155 * @staticvar array $available_translations 1156 * 1157 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 1158 * @param bool $reset Whether to reset the internal cache. Used by the switch to locale functionality. 1159 * @return string|false The path to the translation file or false if no translation file was found. 1160 */ 1161 function _get_path_to_translation( $domain, $reset = false ) { 1162 static $available_translations = array(); 1163 1164 if ( true === $reset ) { 1165 $available_translations = array(); 1166 } 1167 1168 if ( ! isset( $available_translations[ $domain ] ) ) { 1169 $available_translations[ $domain ] = _get_path_to_translation_from_lang_dir( $domain ); 1170 } 1171 1172 return $available_translations[ $domain ]; 1173 } 1174 1175 /** 1176 * Gets the path to a translation file in the languages directory for the current locale. 1177 * 1178 * Holds a cached list of available .mo files to improve performance. 1179 * 1180 * @since 4.7.0 1181 * @access private 1182 * 1183 * @see _get_path_to_translation() 1184 * @staticvar array $cached_mofiles 1185 * 1186 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 1187 * @return string|false The path to the translation file or false if no translation file was found. 1188 */ 1189 function _get_path_to_translation_from_lang_dir( $domain ) { 1190 static $cached_mofiles = null; 1191 1192 if ( null === $cached_mofiles ) { 1193 $cached_mofiles = array(); 1194 1195 $locations = array( 1196 WP_LANG_DIR . '/plugins', 1197 WP_LANG_DIR . '/themes', 1198 ); 1199 1200 foreach ( $locations as $location ) { 1201 $mofiles = glob( $location . '/*.mo' ); 1202 if ( $mofiles ) { 1203 $cached_mofiles = array_merge( $cached_mofiles, $mofiles ); 1204 } 1205 } 1206 } 1207 1208 $locale = determine_locale(); 1209 $mofile = "{$domain}-{$locale}.mo"; 1210 1211 $path = WP_LANG_DIR . '/plugins/' . $mofile; 1212 if ( in_array( $path, $cached_mofiles ) ) { 1213 return $path; 1214 } 1215 1216 $path = WP_LANG_DIR . '/themes/' . $mofile; 1217 if ( in_array( $path, $cached_mofiles ) ) { 1218 return $path; 1219 } 1220 1221 return false; 1222 } 1223 1224 /** 1225 * Return the Translations instance for a text domain. 1226 * 1227 * If there isn't one, returns empty Translations instance. 1228 * 1229 * @since 2.8.0 1230 * 1231 * @global MO[] $l10n 1232 * @staticvar NOOP_Translations $noop_translations 1233 * 1234 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 1235 * @return Translations|NOOP_Translations A Translations instance. 1236 */ 1237 function get_translations_for_domain( $domain ) { 1238 global $l10n; 1239 if ( isset( $l10n[ $domain ] ) || ( _load_textdomain_just_in_time( $domain ) && isset( $l10n[ $domain ] ) ) ) { 1240 return $l10n[ $domain ]; 1241 } 1242 1243 static $noop_translations = null; 1244 if ( null === $noop_translations ) { 1245 $noop_translations = new NOOP_Translations; 1246 } 1247 1248 return $noop_translations; 1249 } 1250 1251 /** 1252 * Whether there are translations for the text domain. 1253 * 1254 * @since 3.0.0 1255 * 1256 * @global MO[] $l10n 1257 * 1258 * @param string $domain Text domain. Unique identifier for retrieving translated strings. 1259 * @return bool Whether there are translations. 1260 */ 1261 function is_textdomain_loaded( $domain ) { 1262 global $l10n; 1263 return isset( $l10n[ $domain ] ); 1264 } 1265 1266 /** 1267 * Translates role name. 1268 * 1269 * Since the role names are in the database and not in the source there 1270 * are dummy gettext calls to get them into the POT file and this function 1271 * properly translates them back. 1272 * 1273 * The before_last_bar() call is needed, because older installations keep the roles 1274 * using the old context format: 'Role name|User role' and just skipping the 1275 * content after the last bar is easier than fixing them in the DB. New installations 1276 * won't suffer from that problem. 1277 * 1278 * @since 2.8.0 1279 * @since 5.2.0 Added the `$domain` parameter. 1280 * 1281 * @param string $name The role name. 1282 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. 1283 * Default 'default'. 1284 * @return string Translated role name on success, original name on failure. 1285 */ 1286 function translate_user_role( $name, $domain = 'default' ) { 1287 return translate_with_gettext_context( before_last_bar( $name ), 'User role', $domain ); 1288 } 1289 1290 /** 1291 * Get all available languages based on the presence of *.mo files in a given directory. 1292 * 1293 * The default directory is WP_LANG_DIR. 1294 * 1295 * @since 3.0.0 1296 * @since 4.7.0 The results are now filterable with the {@see 'get_available_languages'} filter. 1297 * 1298 * @param string $dir A directory to search for language files. 1299 * Default WP_LANG_DIR. 1300 * @return string[] An array of language codes or an empty array if no languages are present. Language codes are formed by stripping the .mo extension from the language file names. 1301 */ 1302 function get_available_languages( $dir = null ) { 1303 $languages = array(); 1304 1305 $lang_files = glob( ( is_null( $dir ) ? WP_LANG_DIR : $dir ) . '/*.mo' ); 1306 if ( $lang_files ) { 1307 foreach ( $lang_files as $lang_file ) { 1308 $lang_file = basename( $lang_file, '.mo' ); 1309 if ( 0 !== strpos( $lang_file, 'continents-cities' ) && 0 !== strpos( $lang_file, 'ms-' ) && 1310 0 !== strpos( $lang_file, 'admin-' ) ) { 1311 $languages[] = $lang_file; 1312 } 1313 } 1314 } 1315 1316 /** 1317 * Filters the list of available language codes. 1318 * 1319 * @since 4.7.0 1320 * 1321 * @param string[] $languages An array of available language codes. 1322 * @param string $dir The directory where the language files were found. 1323 */ 1324 return apply_filters( 'get_available_languages', $languages, $dir ); 1325 } 1326 1327 /** 1328 * Get installed translations. 1329 * 1330 * Looks in the wp-content/languages directory for translations of 1331 * plugins or themes. 1332 * 1333 * @since 3.7.0 1334 * 1335 * @param string $type What to search for. Accepts 'plugins', 'themes', 'core'. 1336 * @return array Array of language data. 1337 */ 1338 function wp_get_installed_translations( $type ) { 1339 if ( $type !== 'themes' && $type !== 'plugins' && $type !== 'core' ) { 1340 return array(); 1341 } 1342 1343 $dir = 'core' === $type ? '' : "/$type"; 1344 1345 if ( ! is_dir( WP_LANG_DIR ) ) { 1346 return array(); 1347 } 1348 1349 if ( $dir && ! is_dir( WP_LANG_DIR . $dir ) ) { 1350 return array(); 1351 } 1352 1353 $files = scandir( WP_LANG_DIR . $dir ); 1354 if ( ! $files ) { 1355 return array(); 1356 } 1357 1358 $language_data = array(); 1359 1360 foreach ( $files as $file ) { 1361 if ( '.' === $file[0] || is_dir( WP_LANG_DIR . "$dir/$file" ) ) { 1362 continue; 1363 } 1364 if ( substr( $file, -3 ) !== '.po' ) { 1365 continue; 1366 } 1367 if ( ! preg_match( '/(?:(.+)-)?([a-z]{2,3}(?:_[A-Z]{2})?(?:_[a-z0-9]+)?).po/', $file, $match ) ) { 1368 continue; 1369 } 1370 if ( ! in_array( substr( $file, 0, -3 ) . '.mo', $files ) ) { 1371 continue; 1372 } 1373 1374 list( , $textdomain, $language ) = $match; 1375 if ( '' === $textdomain ) { 1376 $textdomain = 'default'; 1377 } 1378 $language_data[ $textdomain ][ $language ] = wp_get_pomo_file_data( WP_LANG_DIR . "$dir/$file" ); 1379 } 1380 return $language_data; 1381 } 1382 1383 /** 1384 * Extract headers from a PO file. 1385 * 1386 * @since 3.7.0 1387 * 1388 * @param string $po_file Path to PO file. 1389 * @return string[] Array of PO file header values keyed by header name. 1390 */ 1391 function wp_get_pomo_file_data( $po_file ) { 1392 $headers = get_file_data( 1393 $po_file, 1394 array( 1395 'POT-Creation-Date' => '"POT-Creation-Date', 1396 'PO-Revision-Date' => '"PO-Revision-Date', 1397 'Project-Id-Version' => '"Project-Id-Version', 1398 'X-Generator' => '"X-Generator', 1399 ) 1400 ); 1401 foreach ( $headers as $header => $value ) { 1402 // Remove possible contextual '\n' and closing double quote. 1403 $headers[ $header ] = preg_replace( '~(\\\n)?"$~', '', $value ); 1404 } 1405 return $headers; 1406 } 1407 1408 /** 1409 * Language selector. 1410 * 1411 * @since 4.0.0 1412 * @since 4.3.0 Introduced the `echo` argument. 1413 * @since 4.7.0 Introduced the `show_option_site_default` argument. 1414 * @since 5.1.0 Introduced the `show_option_en_us` argument. 1415 * 1416 * @see get_available_languages() 1417 * @see wp_get_available_translations() 1418 * 1419 * @param string|array $args { 1420 * Optional. Array or string of arguments for outputting the language selector. 1421 * 1422 * @type string $id ID attribute of the select element. Default 'locale'. 1423 * @type string $name Name attribute of the select element. Default 'locale'. 1424 * @type array $languages List of installed languages, contain only the locales. 1425 * Default empty array. 1426 * @type array $translations List of available translations. Default result of 1427 * wp_get_available_translations(). 1428 * @type string $selected Language which should be selected. Default empty. 1429 * @type bool|int $echo Whether to echo the generated markup. Accepts 0, 1, or their 1430 * boolean equivalents. Default 1. 1431 * @type bool $show_available_translations Whether to show available translations. Default true. 1432 * @type bool $show_option_site_default Whether to show an option to fall back to the site's locale. Default false. 1433 * @type bool $show_option_en_us Whether to show an option for English (United States). Default true. 1434 * } 1435 * @return string HTML content 1436 */ 1437 function wp_dropdown_languages( $args = array() ) { 1438 1439 $parsed_args = wp_parse_args( 1440 $args, 1441 array( 1442 'id' => 'locale', 1443 'name' => 'locale', 1444 'languages' => array(), 1445 'translations' => array(), 1446 'selected' => '', 1447 'echo' => 1, 1448 'show_available_translations' => true, 1449 'show_option_site_default' => false, 1450 'show_option_en_us' => true, 1451 ) 1452 ); 1453 1454 // Bail if no ID or no name. 1455 if ( ! $parsed_args['id'] || ! $parsed_args['name'] ) { 1456 return; 1457 } 1458 1459 // English (United States) uses an empty string for the value attribute. 1460 if ( 'en_US' === $parsed_args['selected'] ) { 1461 $parsed_args['selected'] = ''; 1462 } 1463 1464 $translations = $parsed_args['translations']; 1465 if ( empty( $translations ) ) { 1466 require_once ( ABSPATH . 'wp-admin/includes/translation-install.php' ); 1467 $translations = wp_get_available_translations(); 1468 } 1469 1470 /* 1471 * $parsed_args['languages'] should only contain the locales. Find the locale in 1472 * $translations to get the native name. Fall back to locale. 1473 */ 1474 $languages = array(); 1475 foreach ( $parsed_args['languages'] as $locale ) { 1476 if ( isset( $translations[ $locale ] ) ) { 1477 $translation = $translations[ $locale ]; 1478 $languages[] = array( 1479 'language' => $translation['language'], 1480 'native_name' => $translation['native_name'], 1481 'lang' => current( $translation['iso'] ), 1482 ); 1483 1484 // Remove installed language from available translations. 1485 unset( $translations[ $locale ] ); 1486 } else { 1487 $languages[] = array( 1488 'language' => $locale, 1489 'native_name' => $locale, 1490 'lang' => '', 1491 ); 1492 } 1493 } 1494 1495 $translations_available = ( ! empty( $translations ) && $parsed_args['show_available_translations'] ); 1496 1497 // Holds the HTML markup. 1498 $structure = array(); 1499 1500 // List installed languages. 1501 if ( $translations_available ) { 1502 $structure[] = '<optgroup label="' . esc_attr_x( 'Installed', 'translations' ) . '">'; 1503 } 1504 1505 // Site default. 1506 if ( $parsed_args['show_option_site_default'] ) { 1507 $structure[] = sprintf( 1508 '<option value="site-default" data-installed="1"%s>%s</option>', 1509 selected( 'site-default', $parsed_args['selected'], false ), 1510 _x( 'Site Default', 'default site language' ) 1511 ); 1512 } 1513 1514 if ( $parsed_args['show_option_en_us'] ) { 1515 $structure[] = sprintf( 1516 '<option value="" lang="en" data-installed="1"%s>English (United States)</option>', 1517 selected( '', $parsed_args['selected'], false ) 1518 ); 1519 } 1520 1521 // List installed languages. 1522 foreach ( $languages as $language ) { 1523 $structure[] = sprintf( 1524 '<option value="%s" lang="%s"%s data-installed="1">%s</option>', 1525 esc_attr( $language['language'] ), 1526 esc_attr( $language['lang'] ), 1527 selected( $language['language'], $parsed_args['selected'], false ), 1528 esc_html( $language['native_name'] ) 1529 ); 1530 } 1531 if ( $translations_available ) { 1532 $structure[] = '</optgroup>'; 1533 } 1534 1535 // List available translations. 1536 if ( $translations_available ) { 1537 $structure[] = '<optgroup label="' . esc_attr_x( 'Available', 'translations' ) . '">'; 1538 foreach ( $translations as $translation ) { 1539 $structure[] = sprintf( 1540 '<option value="%s" lang="%s"%s>%s</option>', 1541 esc_attr( $translation['language'] ), 1542 esc_attr( current( $translation['iso'] ) ), 1543 selected( $translation['language'], $parsed_args['selected'], false ), 1544 esc_html( $translation['native_name'] ) 1545 ); 1546 } 1547 $structure[] = '</optgroup>'; 1548 } 1549 1550 // Combine the output string. 1551 $output = sprintf( '<select name="%s" id="%s">', esc_attr( $parsed_args['name'] ), esc_attr( $parsed_args['id'] ) ); 1552 $output .= join( "\n", $structure ); 1553 $output .= '</select>'; 1554 1555 if ( $parsed_args['echo'] ) { 1556 echo $output; 1557 } 1558 1559 return $output; 1560 } 1561 1562 /** 1563 * Determines whether the current locale is right-to-left (RTL). 1564 * 1565 * For more information on this and similar theme functions, check out 1566 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 1567 * Conditional Tags} article in the Theme Developer Handbook. 1568 * 1569 * @since 3.0.0 1570 * 1571 * @global WP_Locale $wp_locale WordPress date and time locale object. 1572 * 1573 * @return bool Whether locale is RTL. 1574 */ 1575 function is_rtl() { 1576 global $wp_locale; 1577 if ( ! ( $wp_locale instanceof WP_Locale ) ) { 1578 return false; 1579 } 1580 return $wp_locale->is_rtl(); 1581 } 1582 1583 /** 1584 * Switches the translations according to the given locale. 1585 * 1586 * @since 4.7.0 1587 * 1588 * @global WP_Locale_Switcher $wp_locale_switcher WordPress locale switcher object. 1589 * 1590 * @param string $locale The locale. 1591 * @return bool True on success, false on failure. 1592 */ 1593 function switch_to_locale( $locale ) { 1594 /* @var WP_Locale_Switcher $wp_locale_switcher */ 1595 global $wp_locale_switcher; 1596 1597 return $wp_locale_switcher->switch_to_locale( $locale ); 1598 } 1599 1600 /** 1601 * Restores the translations according to the previous locale. 1602 * 1603 * @since 4.7.0 1604 * 1605 * @global WP_Locale_Switcher $wp_locale_switcher WordPress locale switcher object. 1606 * 1607 * @return string|false Locale on success, false on error. 1608 */ 1609 function restore_previous_locale() { 1610 /* @var WP_Locale_Switcher $wp_locale_switcher */ 1611 global $wp_locale_switcher; 1612 1613 return $wp_locale_switcher->restore_previous_locale(); 1614 } 1615 1616 /** 1617 * Restores the translations according to the original locale. 1618 * 1619 * @since 4.7.0 1620 * 1621 * @global WP_Locale_Switcher $wp_locale_switcher WordPress locale switcher object. 1622 * 1623 * @return string|false Locale on success, false on error. 1624 */ 1625 function restore_current_locale() { 1626 /* @var WP_Locale_Switcher $wp_locale_switcher */ 1627 global $wp_locale_switcher; 1628 1629 return $wp_locale_switcher->restore_current_locale(); 1630 } 1631 1632 /** 1633 * Whether switch_to_locale() is in effect. 1634 * 1635 * @since 4.7.0 1636 * 1637 * @global WP_Locale_Switcher $wp_locale_switcher WordPress locale switcher object. 1638 * 1639 * @return bool True if the locale has been switched, false otherwise. 1640 */ 1641 function is_locale_switched() { 1642 /* @var WP_Locale_Switcher $wp_locale_switcher */ 1643 global $wp_locale_switcher; 1644 1645 return $wp_locale_switcher->is_switched(); 1646 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Sat Nov 23 20:47:33 2019 | Cross-referenced by PHPXref 0.7 |