Make WordPress Core

Ticket #34127: 34127.diff

File 34127.diff, 15.1 KB (added by johnbillion, 9 years ago)
  • src/wp-includes/l10n.php

     
    8080 *
    8181 * If there is no translation, or the text domain isn't loaded, the original text is returned.
    8282 *
    83  * *Note:* Don't use {@see translate()} directly, use `{@see __()} or related functions.
     83 * *Note:* Don't use {@see translate()} directly, use {@see __()} or related functions.
    8484 *
    8585 * @since 2.2.0
    8686 *
    8787 * @param string $text   Text to translate.
    8888 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
     89 *                       Default 'default'.
    8990 * @return string Translated text
    9091 */
    9192function translate( $text, $domain = 'default' ) {
     
    129130 * If there is no translation, or the text domain isn't loaded the original
    130131 * text is returned.
    131132 *
     133 * *Note:* Don't use {@see translate_with_gettext_context()} directly, use {@see _x()} or related functions.
     134 *
    132135 * @since 2.8.0
    133136 *
    134137 * @param string $text    Text to translate.
    135138 * @param string $context Context information for the translators.
    136139 * @param string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.
     140 *                        Default 'default'.
    137141 * @return string Translated text on success, original text on failure.
    138142 */
    139143function translate_with_gettext_context( $text, $context, $domain = 'default' ) {
     
    177181 *
    178182 * @param string $text   Text to translate.
    179183 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
     184 *                       Default 'default'.
    180185 * @return string Translated text on success, original text on failure.
    181186 */
    182187function esc_attr__( $text, $domain = 'default' ) {
     
    192197 *
    193198 * @param string $text   Text to translate.
    194199 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
     200 *                       Default 'default'.
    195201 * @return string Translated text
    196202 */
    197203function esc_html__( $text, $domain = 'default' ) {
     
    205211 *
    206212 * @param string $text   Text to translate.
    207213 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
     214 *                       Default 'default'.
    208215 */
    209216function _e( $text, $domain = 'default' ) {
    210217        echo translate( $text, $domain );
     
    217224 *
    218225 * @param string $text   Text to translate.
    219226 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
     227 *                       Default 'default'.
    220228 */
    221229function esc_attr_e( $text, $domain = 'default' ) {
    222230        echo esc_attr( translate( $text, $domain ) );
     
    229237 *
    230238 * @param string $text   Text to translate.
    231239 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
     240 *                       Default 'default'.
    232241 */
    233242function esc_html_e( $text, $domain = 'default' ) {
    234243        echo esc_html( translate( $text, $domain ) );
     
    248257 * @param string $text    Text to translate.
    249258 * @param string $context Context information for the translators.
    250259 * @param string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.
     260 *                        Default 'default'.
    251261 * @return string Translated context string without pipe.
    252262 */
    253263function _x( $text, $context, $domain = 'default' ) {
     
    262272 * @param string $text    Text to translate.
    263273 * @param string $context Context information for the translators.
    264274 * @param string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.
     275 *                        Default 'default'.
    265276 * @return string Translated context string without pipe.
    266277 */
    267278function _ex( $text, $context, $domain = 'default' ) {
     
    276287 * @param string $text    Text to translate.
    277288 * @param string $context Context information for the translators.
    278289 * @param string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.
     290 *                        Default 'default'.
    279291 * @return string Translated text
    280292 */
    281293function esc_attr_x( $text, $context, $domain = 'default' ) {
     
    290302 * @param string $text    Text to translate.
    291303 * @param string $context Context information for the translators.
    292304 * @param string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.
     305 *                        Default 'default'.
    293306 * @return string Translated text.
    294307 */
    295308function esc_html_x( $text, $context, $domain = 'default' ) {
     
    297310}
    298311
    299312/**
    300  * Retrieve the plural or single form based on the supplied amount.
     313 * Translate and retrieve the singular or plural form based on the supplied number.
    301314 *
    302  * If the text domain is not set in the $l10n list, then a comparison will be made
    303  * and either $plural or $single parameters returned.
     315 * Used when you want to use the appropriate form of a string based on whether a
     316 * number is singular or plural.
     317 *
     318 * Example:
    304319 *
    305  * If the text domain does exist, then the parameters $single, $plural, and $number
    306  * will first be passed to the text domain's ngettext method. Then it will be passed
    307  * to the 'ngettext' filter hook along with the same parameters. The expected
    308  * type will be a string.
     320 *     $people = sprintf( _n( '%s person', '%s people', $count, 'text-domain' ), number_format_i18n( $count ) );
    309321 *
    310322 * @since 2.8.0
    311323 *
    312  * @param string $single The text that will be used if $number is 1.
    313  * @param string $plural The text that will be used if $number is not 1.
    314  * @param int    $number The number to compare against to use either $single or $plural.
     324 * @param string $single The text to be used if the number is singular.
     325 * @param string $plural The text to be used if the number is plural.
     326 * @param int    $number The number to compare against to use either the singular or plural form.
    315327 * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
    316  * @return string Either $single or $plural translated text.
     328 *                       Default 'default'.
     329 * @return string The translated singular or plural form.
    317330 */
    318331function _n( $single, $plural, $number, $domain = 'default' ) {
    319332        $translations = get_translations_for_domain( $domain );
    320333        $translation = $translations->translate_plural( $single, $plural, $number );
    321334        /**
    322          * Filter text with its translation when plural option is available.
     335         * Filter the singular or plural form of a string.
    323336         *
    324337         * @since 2.2.0
    325338         *
    326339         * @param string $translation Translated text.
    327          * @param string $single      The text that will be used if $number is 1.
    328          * @param string $plural      The text that will be used if $number is not 1.
    329          * @param string $number      The number to compare against to use either $single or $plural.
     340         * @param string $single      The text to be used if the number is singular.
     341         * @param string $plural      The text to be used if the number is plural.
     342         * @param string $number      The number to compare against to use either the singular or plural form.
    330343         * @param string $domain      Text domain. Unique identifier for retrieving translated strings.
    331344         */
    332345        return apply_filters( 'ngettext', $translation, $single, $plural, $number, $domain );
    333346}
    334347
    335348/**
    336  * Retrieve the plural or single form based on the supplied amount with gettext context.
     349 * Translate and retrieve the singular or plural form based on the supplied number, with gettext context.
     350 *
     351 * This is a hybrid of _n() and _x(). It supports context and plurals.
    337352 *
    338  * This is a hybrid of _n() and _x(). It supports contexts and plurals.
     353 * Used when you want to use the appropriate form of a string with context based on whether a
     354 * number is singular or plural.
     355 *
     356 * Example:
     357 *
     358 *     $people = sprintf( _n( '%s person', '%s people', $count, 'context', 'text-domain' ), number_format_i18n( $count ) );
    339359 *
    340360 * @since 2.8.0
    341361 *
    342  * @param string $single  The text that will be used if $number is 1.
    343  * @param string $plural  The text that will be used if $number is not 1.
    344  * @param int    $number  The number to compare against to use either $single or $plural.
     362 * @param string $single  The text to be used if the number is singular.
     363 * @param string $plural  The text to be used if the number is plural.
     364 * @param int    $number  The number to compare against to use either the singular or plural form.
    345365 * @param string $context Context information for the translators.
    346366 * @param string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.
    347  * @return string Either $single or $plural translated text with context.
     367 *                        Default 'default'.
     368 * @return string The translated singular or plural form.
    348369 */
    349370function _nx($single, $plural, $number, $context, $domain = 'default') {
    350371        $translations = get_translations_for_domain( $domain );
    351372        $translation = $translations->translate_plural( $single, $plural, $number, $context );
    352373        /**
    353          * Filter text with its translation while plural option and context are available.
     374         * Filter the singular or plural form of a string with gettext context.
    354375         *
    355376         * @since 2.8.0
    356377         *
    357378         * @param string $translation Translated text.
    358          * @param string $single      The text that will be used if $number is 1.
    359          * @param string $plural      The text that will be used if $number is not 1.
    360          * @param string $number      The number to compare against to use either $single or $plural.
     379         * @param string $single      The text to be used if the number is singular.
     380         * @param string $plural      The text to be used if the number is plural.
     381         * @param string $number      The number to compare against to use either the singular or plural form.
    361382         * @param string $context     Context information for the translators.
    362383         * @param string $domain      Text domain. Unique identifier for retrieving translated strings.
    363384         */
     
    368389 * Register plural strings in POT file, but don't translate them.
    369390 *
    370391 * Used when you want to keep structures with translatable plural
    371  * strings and use them later.
     392 * strings and use them later when the number is known.
    372393 *
    373394 * Example:
    374395 *
    375396 *     $messages = array(
    376  *              'post' => _n_noop( '%s post', '%s posts' ),
    377  *              'page' => _n_noop( '%s pages', '%s pages' ),
     397 *              'post' => _n_noop( '%s post', '%s posts', 'text-domain' ),
     398 *              'page' => _n_noop( '%s pages', '%s pages', 'text-domain' ),
    378399 *     );
    379400 *     ...
    380401 *     $message = $messages[ $type ];
    381  *     $usable_text = sprintf( translate_nooped_plural( $message, $count ), $count );
     402 *     $usable_text = sprintf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
    382403 *
    383404 * @since 2.5.0
    384405 *
    385  * @param string $singular Single form to be i18ned.
    386  * @param string $plural   Plural form to be i18ned.
     406 * @param string $singular Singular form to be localized.
     407 * @param string $plural   Plural form to be localized.
    387408 * @param string $domain   Optional. Text domain. Unique identifier for retrieving translated strings.
    388  * @return array array($singular, $plural)
     409 *                         Default null.
     410 * @return array {
     411 *     Array of translation information for the strings.
     412 *
     413 *     @type string $0        Singular form to be localized. No longer used.
     414 *     @type string $1        Plural form to be localized. No longer used.
     415 *     @type string $singular Singular form to be localized.
     416 *     @type string $plural   Plural form to be localized.
     417 *     @type null   $context  Context information for the translators.
     418 *     @type string $domain   Text domain.
     419 * }
    389420 */
    390421function _n_noop( $singular, $plural, $domain = null ) {
    391422        return array( 0 => $singular, 1 => $plural, 'singular' => $singular, 'plural' => $plural, 'context' => null, 'domain' => $domain );
    392423}
    393424
    394425/**
    395  * Register plural strings with context in POT file, but don't translate them.
     426 * Register plural strings with gettext context in POT file, but don't translate them.
     427 *
     428 * Used when you want to keep structures with translatable plural
     429 * strings and use them later when the number is known.
     430 *
     431 * Example:
     432 *
     433 *     $messages = array(
     434 *              'post' => _n_noop( '%s post', '%s posts', 'context', 'text-domain' ),
     435 *              'page' => _n_noop( '%s pages', '%s pages', 'context', 'text-domain' ),
     436 *     );
     437 *     ...
     438 *     $message = $messages[ $type ];
     439 *     $usable_text = sprintf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
    396440 *
    397441 * @since 2.8.0
    398  * @param string $singular
    399  * @param string $plural
    400  * @param string $context
    401  * @param string|null $domain
    402  * @return array
     442 *
     443 * @param string $singular Singular form to be localized.
     444 * @param string $plural   Plural form to be localized.
     445 * @param string $domain   Optional. Text domain. Unique identifier for retrieving translated strings.
     446 *                         Default null.
     447 * @return array {
     448 *     Array of translation information for the strings.
     449 *
     450 *     @type string $0        Singular form to be localized. No longer used.
     451 *     @type string $1        Plural form to be localized. No longer used.
     452 *     @type string $2        Context information for the translators. No longer used.
     453 *     @type string $singular Singular form to be localized.
     454 *     @type string $plural   Plural form to be localized.
     455 *     @type string $context  Context information for the translators.
     456 *     @type string $domain   Text domain.
     457 * }
    403458 */
    404459function _nx_noop( $singular, $plural, $context, $domain = null ) {
    405460        return array( 0 => $singular, 1 => $plural, 2 => $context, 'singular' => $singular, 'plural' => $plural, 'context' => $context, 'domain' => $domain );
    406461}
    407462
    408463/**
    409  * Translate the result of _n_noop() or _nx_noop().
     464 * Translate and retrieve the singular or plural form of a string that's been registered with _n_noop() or _nx_noop().
     465 *
     466 * Used when you want to use a translatable plural string once the number is known.
     467 *
     468 * Example:
     469 *
     470 *     $messages = array(
     471 *              'post' => _n_noop( '%s post', '%s posts', 'text-domain' ),
     472 *              'page' => _n_noop( '%s pages', '%s pages', 'text-domain' ),
     473 *     );
     474 *     ...
     475 *     $message = $messages[ $type ];
     476 *     $usable_text = sprintf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
    410477 *
    411478 * @since 3.1.0
    412479 *
    413  * @param array  $nooped_plural Array with singular, plural and context keys, usually the result of _n_noop() or _nx_noop()
    414  * @param int    $count         Number of objects
     480 * @param array  $nooped_plural Array with singular, plural, and context keys, usually the result of _n_noop() or _nx_noop().
     481 * @param int    $count         Number of objects.
    415482 * @param string $domain        Optional. Text domain. Unique identifier for retrieving translated strings. If $nooped_plural contains
    416  *                              a text domain passed to _n_noop() or _nx_noop(), it will override this value.
     483 *                              a text domain passed to _n_noop() or _nx_noop(), it will override this value. Default 'default'.
    417484 * @return string Either $single or $plural translated text.
    418485 */
    419486function translate_nooped_plural( $nooped_plural, $count, $domain = 'default' ) {