WordPress.org
Get WordPress

Make WordPress Core

Changeset 34781


Ignore:
Timestamp:
10/02/2015 08:44:18 PM (9 years ago)
Author:
DrewAPicture
Message:

Docs: Improve a variety of inline docs in wp-includes/l10n.php.

  • Corrects phrasing used in the descriptions for and filters in _n() and _nx(), particularly with regard to the use of 'singular' instead of 'single' or '1', and 'plural' instead of 'not 1'.
  • Adds example usage to _n(), _nx(), _nx_noop(), and translate_nooped_plural().
  • Adds hash notation @return doc for _n_noop() and _nx_noop().
  • Adds missing default values for the optional $domain parameter in several places.

Props johnbillion.
Fixes #34127.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/l10n.php

    r34778 r34781  
    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 translate() directly, use __() or related functions.
    8484 *
    8585 * @since 2.2.0
    … …  
    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 */
    … …  
    130131 * text is returned.
    131132 *
     133 * *Note:* Don't use translate_with_gettext_context() directly, use _x() or related functions.
     134 *
    132135 * @since 2.8.0
    133136 *
    … …  
    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 */
    … …  
    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 */
    … …  
    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 */
    … …  
    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' ) {
    … …  
    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' ) {
    … …  
    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' ) {
    … …  
    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 */
    … …  
    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 */
    … …  
    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 */
    … …  
    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 */
    … …  
    298311
    299312/**
    300  * Retrieve the plural or single form based on the supplied amount.
    301  *
    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.
    304  *
    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.
    309  *
    310  * @since 2.8.0
    311  *
    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.
     313 * Translates and retrieves the singular or plural form based on the supplied number.
     314 *
     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:
     319 *
     320 *     $people = sprintf( _n( '%s person', '%s people', $count, 'text-domain' ), number_format_i18n( $count ) );
     321 *
     322 * @since 2.8.0
     323 *
     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 );
     334
    321335    /**
    322      * Filter text with its translation when plural option is available.
     336     * Filter the singular or plural form of a string.
    323337     *
    324338     * @since 2.2.0
    325339     *
    326340     * @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.
     341     * @param string $single      The text to be used if the number is singular.
     342     * @param string $plural      The text to be used if the number is plural.
     343     * @param string $number      The number to compare against to use either the singular or plural form.
    330344     * @param string $domain      Text domain. Unique identifier for retrieving translated strings.
    331345     */
    … …  
    334348
    335349/**
    336  * Retrieve the plural or single form based on the supplied amount with gettext context.
    337  *
    338  * This is a hybrid of _n() and _x(). It supports contexts and plurals.
    339  *
    340  * @since 2.8.0
    341  *
    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.
     350 * Translates and retrieves the singular or plural form based on the supplied number, with gettext context.
     351 *
     352 * This is a hybrid of _n() and _x(). It supports context and plurals.
     353 *
     354 * Used when you want to use the appropriate form of a string with context based on whether a
     355 * number is singular or plural.
     356 *
     357 * Example:
     358 *
     359 *     $people = sprintf( _n( '%s person', '%s people', $count, 'context', 'text-domain' ), number_format_i18n( $count ) );
     360 *
     361 * @since 2.8.0
     362 *
     363 * @param string $single  The text to be used if the number is singular.
     364 * @param string $plural  The text to be used if the number is plural.
     365 * @param int    $number  The number to compare against to use either the singular or plural form.
    345366 * @param string $context Context information for the translators.
    346367 * @param string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.
    347  * @return string Either $single or $plural translated text with context.
     368 *                        Default 'default'.
     369 * @return string The translated singular or plural form.
    348370 */
    349371function _nx($single, $plural, $number, $context, $domain = 'default') {
    350372    $translations = get_translations_for_domain( $domain );
    351373    $translation = $translations->translate_plural( $single, $plural, $number, $context );
     374
    352375    /**
    353      * Filter text with its translation while plural option and context are available.
     376     * Filter the singular or plural form of a string with gettext context.
    354377     *
    355378     * @since 2.8.0
    356379     *
    357380     * @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.
     381     * @param string $single      The text to be used if the number is singular.
     382     * @param string $plural      The text to be used if the number is plural.
     383     * @param string $number      The number to compare against to use either the singular or plural form.
    361384     * @param string $context     Context information for the translators.
    362385     * @param string $domain      Text domain. Unique identifier for retrieving translated strings.
    … …  
    366389
    367390/**
    368  * Register plural strings in POT file, but don't translate them.
     391 * Registers plural strings in POT file, but don't translate them.
    369392 *
    370393 * Used when you want to keep structures with translatable plural
    371  * strings and use them later.
     394 * strings and use them later when the number is known.
    372395 *
    373396 * Example:
    374397 *
    375398 *     $messages = array(
    376  *          'post' => _n_noop( '%s post', '%s posts' ),
    377  *          'page' => _n_noop( '%s pages', '%s pages' ),
     399 *          'post' => _n_noop( '%s post', '%s posts', 'text-domain' ),
     400 *          'page' => _n_noop( '%s pages', '%s pages', 'text-domain' ),
    378401 *     );
    379402 *     ...
    380403 *     $message = $messages[ $type ];
    381  *     $usable_text = sprintf( translate_nooped_plural( $message, $count ), $count );
     404 *     $usable_text = sprintf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
    382405 *
    383406 * @since 2.5.0
    384407 *
    385  * @param string $singular Single form to be i18ned.
    386  * @param string $plural   Plural form to be i18ned.
     408 * @param string $singular Singular form to be localized.
     409 * @param string $plural   Plural form to be localized.
    387410 * @param string $domain   Optional. Text domain. Unique identifier for retrieving translated strings.
    388  * @return array array($singular, $plural)
     411 *                         Default null.
     412 * @return array {
     413 *     Array of translation information for the strings.
     414 *
     415 *     @type string $0        Singular form to be localized. No longer used.
     416 *     @type string $1        Plural form to be localized. No longer used.
     417 *     @type string $singular Singular form to be localized.
     418 *     @type string $plural   Plural form to be localized.
     419 *     @type null   $context  Context information for the translators.
     420 *     @type string $domain   Text domain.
     421 * }
    389422 */
    390423function _n_noop( $singular, $plural, $domain = null ) {
    … …  
    393426
    394427/**
    395  * Register plural strings with context in POT file, but don't translate them.
    396  *
    397  * @since 2.8.0
    398  * @param string $singular
    399  * @param string $plural
    400  * @param string $context
    401  * @param string|null $domain
    402  * @return array
     428 * Register plural strings with gettext context in the POT file, but don't translate them.
     429 *
     430 * Used when you want to keep structures with translatable plural
     431 * strings and use them later when the number is known.
     432 *
     433 * Example:
     434 *
     435 *     $messages = array(
     436 *          'post' => _n_noop( '%s post', '%s posts', 'context', 'text-domain' ),
     437 *          'page' => _n_noop( '%s pages', '%s pages', 'context', 'text-domain' ),
     438 *     );
     439 *     ...
     440 *     $message = $messages[ $type ];
     441 *     $usable_text = sprintf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
     442 *
     443 * @since 2.8.0
     444 *
     445 * @param string $singular Singular form to be localized.
     446 * @param string $plural   Plural form to be localized.
     447 * @param string $domain   Optional. Text domain. Unique identifier for retrieving translated strings.
     448 *                         Default null.
     449 * @return array {
     450 *     Array of translation information for the strings.
     451 *
     452 *     @type string $0        Singular form to be localized. No longer used.
     453 *     @type string $1        Plural form to be localized. No longer used.
     454 *     @type string $2        Context information for the translators. No longer used.
     455 *     @type string $singular Singular form to be localized.
     456 *     @type string $plural   Plural form to be localized.
     457 *     @type string $context  Context information for the translators.
     458 *     @type string $domain   Text domain.
     459 * }
    403460 */
    404461function _nx_noop( $singular, $plural, $context, $domain = null ) {
    … …  
    407464
    408465/**
    409  * Translate the result of _n_noop() or _nx_noop().
     466 * Translates and retrieves the singular or plural form of a string that's been registered
     467 * with _n_noop() or _nx_noop().
     468 *
     469 * Used when you want to use a translatable plural string once the number is known.
     470 *
     471 * Example:
     472 *
     473 *     $messages = array(
     474 *          'post' => _n_noop( '%s post', '%s posts', 'text-domain' ),
     475 *          'page' => _n_noop( '%s pages', '%s pages', 'text-domain' ),
     476 *     );
     477 *     ...
     478 *     $message = $messages[ $type ];
     479 *     $usable_text = sprintf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
    410480 *
    411481 * @since 3.1.0
    412482 *
    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
     483 * @param array  $nooped_plural Array with singular, plural, and context keys, usually the result of _n_noop() or _nx_noop().
     484 * @param int    $count         Number of objects.
    415485 * @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.
     486 *                              a text domain passed to _n_noop() or _nx_noop(), it will override this value. Default 'default'.
    417487 * @return string Either $single or $plural translated text.
    418488 */
Note: See TracChangeset for help on using the changeset viewer.