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.

Built from https://develop.svn.wordpress.org/trunk@34781


git-svn-id: http://core.svn.wordpress.org/trunk@34746 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Drew Jaynes 2015-10-02 20:45:24 +00:00
parent 7707dbf862
commit bfa2a5295e
2 changed files with 115 additions and 45 deletions

View File

@ -80,12 +80,13 @@ function get_locale() {
*
* If there is no translation, or the text domain isn't loaded, the original text is returned.
*
* *Note:* Don't use {@see translate()} directly, use `{@see __()} or related functions.
* *Note:* Don't use translate() directly, use __() or related functions.
*
* @since 2.2.0
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text
*/
function translate( $text, $domain = 'default' ) {
@ -129,11 +130,14 @@ function before_last_bar( $string ) {
* If there is no translation, or the text domain isn't loaded the original
* text is returned.
*
* *Note:* Don't use translate_with_gettext_context() directly, use _x() or related functions.
*
* @since 2.8.0
*
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text on success, original text on failure.
*/
function translate_with_gettext_context( $text, $context, $domain = 'default' ) {
@ -177,6 +181,7 @@ function __( $text, $domain = 'default' ) {
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text on success, original text on failure.
*/
function esc_attr__( $text, $domain = 'default' ) {
@ -192,6 +197,7 @@ function esc_attr__( $text, $domain = 'default' ) {
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text
*/
function esc_html__( $text, $domain = 'default' ) {
@ -205,6 +211,7 @@ function esc_html__( $text, $domain = 'default' ) {
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
*/
function _e( $text, $domain = 'default' ) {
echo translate( $text, $domain );
@ -217,6 +224,7 @@ function _e( $text, $domain = 'default' ) {
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
*/
function esc_attr_e( $text, $domain = 'default' ) {
echo esc_attr( translate( $text, $domain ) );
@ -229,6 +237,7 @@ function esc_attr_e( $text, $domain = 'default' ) {
*
* @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
*/
function esc_html_e( $text, $domain = 'default' ) {
echo esc_html( translate( $text, $domain ) );
@ -248,6 +257,7 @@ function esc_html_e( $text, $domain = 'default' ) {
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated context string without pipe.
*/
function _x( $text, $context, $domain = 'default' ) {
@ -262,6 +272,7 @@ function _x( $text, $context, $domain = 'default' ) {
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated context string without pipe.
*/
function _ex( $text, $context, $domain = 'default' ) {
@ -276,6 +287,7 @@ function _ex( $text, $context, $domain = 'default' ) {
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text
*/
function esc_attr_x( $text, $context, $domain = 'default' ) {
@ -290,6 +302,7 @@ function esc_attr_x( $text, $context, $domain = 'default' ) {
* @param string $text Text to translate.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text.
*/
function esc_html_x( $text, $context, $domain = 'default' ) {
@ -297,67 +310,77 @@ function esc_html_x( $text, $context, $domain = 'default' ) {
}
/**
* Retrieve the plural or single form based on the supplied amount.
* Translates and retrieves the singular or plural form based on the supplied number.
*
* If the text domain is not set in the $l10n list, then a comparison will be made
* and either $plural or $single parameters returned.
* Used when you want to use the appropriate form of a string based on whether a
* number is singular or plural.
*
* If the text domain does exist, then the parameters $single, $plural, and $number
* will first be passed to the text domain's ngettext method. Then it will be passed
* to the 'ngettext' filter hook along with the same parameters. The expected
* type will be a string.
* Example:
*
* $people = sprintf( _n( '%s person', '%s people', $count, 'text-domain' ), number_format_i18n( $count ) );
*
* @since 2.8.0
*
* @param string $single The text that will be used if $number is 1.
* @param string $plural The text that will be used if $number is not 1.
* @param int $number The number to compare against to use either $single or $plural.
* @param string $single The text to be used if the number is singular.
* @param string $plural The text to be used if the number is plural.
* @param int $number The number to compare against to use either the singular or plural form.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* @return string Either $single or $plural translated text.
* Default 'default'.
* @return string The translated singular or plural form.
*/
function _n( $single, $plural, $number, $domain = 'default' ) {
$translations = get_translations_for_domain( $domain );
$translation = $translations->translate_plural( $single, $plural, $number );
/**
* Filter text with its translation when plural option is available.
* Filter the singular or plural form of a string.
*
* @since 2.2.0
*
* @param string $translation Translated text.
* @param string $single The text that will be used if $number is 1.
* @param string $plural The text that will be used if $number is not 1.
* @param string $number The number to compare against to use either $single or $plural.
* @param string $single The text to be used if the number is singular.
* @param string $plural The text to be used if the number is plural.
* @param string $number The number to compare against to use either the singular or plural form.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
return apply_filters( 'ngettext', $translation, $single, $plural, $number, $domain );
}
/**
* Retrieve the plural or single form based on the supplied amount with gettext context.
* Translates and retrieves the singular or plural form based on the supplied number, with gettext context.
*
* This is a hybrid of _n() and _x(). It supports contexts and plurals.
* This is a hybrid of _n() and _x(). It supports context and plurals.
*
* Used when you want to use the appropriate form of a string with context based on whether a
* number is singular or plural.
*
* Example:
*
* $people = sprintf( _n( '%s person', '%s people', $count, 'context', 'text-domain' ), number_format_i18n( $count ) );
*
* @since 2.8.0
*
* @param string $single The text that will be used if $number is 1.
* @param string $plural The text that will be used if $number is not 1.
* @param int $number The number to compare against to use either $single or $plural.
* @param string $single The text to be used if the number is singular.
* @param string $plural The text to be used if the number is plural.
* @param int $number The number to compare against to use either the singular or plural form.
* @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* @return string Either $single or $plural translated text with context.
* Default 'default'.
* @return string The translated singular or plural form.
*/
function _nx($single, $plural, $number, $context, $domain = 'default') {
$translations = get_translations_for_domain( $domain );
$translation = $translations->translate_plural( $single, $plural, $number, $context );
/**
* Filter text with its translation while plural option and context are available.
* Filter the singular or plural form of a string with gettext context.
*
* @since 2.8.0
*
* @param string $translation Translated text.
* @param string $single The text that will be used if $number is 1.
* @param string $plural The text that will be used if $number is not 1.
* @param string $number The number to compare against to use either $single or $plural.
* @param string $single The text to be used if the number is singular.
* @param string $plural The text to be used if the number is plural.
* @param string $number The number to compare against to use either the singular or plural form.
* @param string $context Context information for the translators.
* @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/
@ -365,55 +388,102 @@ function _nx($single, $plural, $number, $context, $domain = 'default') {
}
/**
* Register plural strings in POT file, but don't translate them.
* Registers plural strings in POT file, but don't translate them.
*
* Used when you want to keep structures with translatable plural
* strings and use them later.
* strings and use them later when the number is known.
*
* Example:
*
* $messages = array(
* 'post' => _n_noop( '%s post', '%s posts' ),
* 'page' => _n_noop( '%s pages', '%s pages' ),
* 'post' => _n_noop( '%s post', '%s posts', 'text-domain' ),
* 'page' => _n_noop( '%s pages', '%s pages', 'text-domain' ),
* );
* ...
* $message = $messages[ $type ];
* $usable_text = sprintf( translate_nooped_plural( $message, $count ), $count );
* $usable_text = sprintf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
*
* @since 2.5.0
*
* @param string $singular Single form to be i18ned.
* @param string $plural Plural form to be i18ned.
* @param string $singular Singular form to be localized.
* @param string $plural Plural form to be localized.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* @return array array($singular, $plural)
* Default null.
* @return array {
* Array of translation information for the strings.
*
* @type string $0 Singular form to be localized. No longer used.
* @type string $1 Plural form to be localized. No longer used.
* @type string $singular Singular form to be localized.
* @type string $plural Plural form to be localized.
* @type null $context Context information for the translators.
* @type string $domain Text domain.
* }
*/
function _n_noop( $singular, $plural, $domain = null ) {
return array( 0 => $singular, 1 => $plural, 'singular' => $singular, 'plural' => $plural, 'context' => null, 'domain' => $domain );
}
/**
* Register plural strings with context in POT file, but don't translate them.
* Register plural strings with gettext context in the POT file, but don't translate them.
*
* Used when you want to keep structures with translatable plural
* strings and use them later when the number is known.
*
* Example:
*
* $messages = array(
* 'post' => _n_noop( '%s post', '%s posts', 'context', 'text-domain' ),
* 'page' => _n_noop( '%s pages', '%s pages', 'context', 'text-domain' ),
* );
* ...
* $message = $messages[ $type ];
* $usable_text = sprintf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
*
* @since 2.8.0
* @param string $singular
* @param string $plural
* @param string $context
* @param string|null $domain
* @return array
*
* @param string $singular Singular form to be localized.
* @param string $plural Plural form to be localized.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default null.
* @return array {
* Array of translation information for the strings.
*
* @type string $0 Singular form to be localized. No longer used.
* @type string $1 Plural form to be localized. No longer used.
* @type string $2 Context information for the translators. No longer used.
* @type string $singular Singular form to be localized.
* @type string $plural Plural form to be localized.
* @type string $context Context information for the translators.
* @type string $domain Text domain.
* }
*/
function _nx_noop( $singular, $plural, $context, $domain = null ) {
return array( 0 => $singular, 1 => $plural, 2 => $context, 'singular' => $singular, 'plural' => $plural, 'context' => $context, 'domain' => $domain );
}
/**
* Translate the result of _n_noop() or _nx_noop().
* Translates and retrieves the singular or plural form of a string that's been registered
* with _n_noop() or _nx_noop().
*
* Used when you want to use a translatable plural string once the number is known.
*
* Example:
*
* $messages = array(
* 'post' => _n_noop( '%s post', '%s posts', 'text-domain' ),
* 'page' => _n_noop( '%s pages', '%s pages', 'text-domain' ),
* );
* ...
* $message = $messages[ $type ];
* $usable_text = sprintf( translate_nooped_plural( $message, $count, 'text-domain' ), number_format_i18n( $count ) );
*
* @since 3.1.0
*
* @param array $nooped_plural Array with singular, plural and context keys, usually the result of _n_noop() or _nx_noop()
* @param int $count Number of objects
* @param array $nooped_plural Array with singular, plural, and context keys, usually the result of _n_noop() or _nx_noop().
* @param int $count Number of objects.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. If $nooped_plural contains
* a text domain passed to _n_noop() or _nx_noop(), it will override this value.
* a text domain passed to _n_noop() or _nx_noop(), it will override this value. Default 'default'.
* @return string Either $single or $plural translated text.
*/
function translate_nooped_plural( $nooped_plural, $count, $domain = 'default' ) {

View File

@ -4,7 +4,7 @@
*
* @global string $wp_version
*/
$wp_version = '4.4-alpha-34780';
$wp_version = '4.4-alpha-34781';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.