mirror of
https://github.com/WordPress/WordPress.git
synced 2024-12-31 13:37:51 +01:00
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
parent
7707dbf862
commit
bfa2a5295e
@ -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' ) {
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user