Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2024-06-27 15:24:59 +02:00
Code Issues Projects Releases Wiki Activity

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

Browse Source 
* 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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
wp-includes/l10n.php
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. * 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 * @since 2.2.0
* *
* @param string $text Text to translate. * @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text * @return string Translated text
*/ */
function translate( $text, $domain = 'default' ) { 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 * If there is no translation, or the text domain isn't loaded the original
* text is returned. * text is returned.
* *
* *Note:* Don't use translate_with_gettext_context() directly, use _x() or related functions.
*
* @since 2.8.0 * @since 2.8.0
* *
* @param string $text Text to translate. * @param string $text Text to translate.
* @param string $context Context information for the translators. * @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text on success, original text on failure. * @return string Translated text on success, original text on failure.
*/ */
function translate_with_gettext_context( $text, $context, $domain = 'default' ) { 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 $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text on success, original text on failure. * @return string Translated text on success, original text on failure.
*/ */
function esc_attr__( $text, $domain = 'default' ) { function esc_attr__( $text, $domain = 'default' ) {
@ -192,6 +197,7 @@ function esc_attr__( $text, $domain = 'default' ) {
* *
* @param string $text Text to translate. * @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text * @return string Translated text
*/ */
function esc_html__( $text, $domain = 'default' ) { function esc_html__( $text, $domain = 'default' ) {
@ -205,6 +211,7 @@ function esc_html__( $text, $domain = 'default' ) {
* *
* @param string $text Text to translate. * @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
*/ */
function _e( $text, $domain = 'default' ) { function _e( $text, $domain = 'default' ) {
echo translate( $text, $domain ); echo translate( $text, $domain );
@ -217,6 +224,7 @@ function _e( $text, $domain = 'default' ) {
* *
* @param string $text Text to translate. * @param string $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
*/ */
function esc_attr_e( $text, $domain = 'default' ) { function esc_attr_e( $text, $domain = 'default' ) {
echo esc_attr( translate( $text, $domain ) ); 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 $text Text to translate.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
*/ */
function esc_html_e( $text, $domain = 'default' ) { function esc_html_e( $text, $domain = 'default' ) {
echo esc_html( translate( $text, $domain ) ); 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 $text Text to translate.
* @param string $context Context information for the translators. * @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated context string without pipe. * @return string Translated context string without pipe.
*/ */
function _x( $text, $context, $domain = 'default' ) { function _x( $text, $context, $domain = 'default' ) {
@ -262,6 +272,7 @@ function _x( $text, $context, $domain = 'default' ) {
* @param string $text Text to translate. * @param string $text Text to translate.
* @param string $context Context information for the translators. * @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated context string without pipe. * @return string Translated context string without pipe.
*/ */
function _ex( $text, $context, $domain = 'default' ) { function _ex( $text, $context, $domain = 'default' ) {
@ -276,6 +287,7 @@ function _ex( $text, $context, $domain = 'default' ) {
* @param string $text Text to translate. * @param string $text Text to translate.
* @param string $context Context information for the translators. * @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text * @return string Translated text
*/ */
function esc_attr_x( $text, $context, $domain = 'default' ) { 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 $text Text to translate.
* @param string $context Context information for the translators. * @param string $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* Default 'default'.
* @return string Translated text. * @return string Translated text.
*/ */
function esc_html_x( $text, $context, $domain = 'default' ) { 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 * Used when you want to use the appropriate form of a string based on whether a
* and either $plural or $single parameters returned. * number is singular or plural.
* *
* If the text domain does exist, then the parameters $single, $plural, and $number * Example:
* 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 * $people = sprintf( _n( '%s person', '%s people', $count, 'text-domain' ), number_format_i18n( $count ) );
* type will be a string.
* *
* @since 2.8.0 * @since 2.8.0
* *
* @param string $single The text that will be used if $number is 1. * @param string $single The text to be used if the number is singular.
* @param string $plural The text that will be used if $number is not 1. * @param string $plural The text to be used if the number is plural.
* @param int $number The number to compare against to use either $single or $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. * @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' ) { function _n( $single, $plural, $number, $domain = 'default' ) {
$translations = get_translations_for_domain( $domain ); $translations = get_translations_for_domain( $domain );
$translation = $translations->translate_plural( $single, $plural, $number ); $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 * @since 2.2.0
* *
* @param string $translation Translated text. * @param string $translation Translated text.
* @param string $single The text that will be used if $number is 1. * @param string $single The text to be used if the number is singular.
* @param string $plural The text that will be used if $number is not 1. * @param string $plural The text to be used if the number is plural.
* @param string $number The number to compare against to use either $single or $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. * @param string $domain Text domain. Unique identifier for retrieving translated strings.
*/ */
return apply_filters( 'ngettext', $translation, $single, $plural, $number, $domain ); 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 * @since 2.8.0
* *
* @param string $single The text that will be used if $number is 1. * @param string $single The text to be used if the number is singular.
* @param string $plural The text that will be used if $number is not 1. * @param string $plural The text to be used if the number is plural.
* @param int $number The number to compare against to use either $single or $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 $context Context information for the translators.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @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') { function _nx($single, $plural, $number, $context, $domain = 'default') {
$translations = get_translations_for_domain( $domain ); $translations = get_translations_for_domain( $domain );
$translation = $translations->translate_plural( $single, $plural, $number, $context ); $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 * @since 2.8.0
* *
* @param string $translation Translated text. * @param string $translation Translated text.
* @param string $single The text that will be used if $number is 1. * @param string $single The text to be used if the number is singular.
* @param string $plural The text that will be used if $number is not 1. * @param string $plural The text to be used if the number is plural.
* @param string $number The number to compare against to use either $single or $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 $context Context information for the translators.
* @param string $domain Text domain. Unique identifier for retrieving translated strings. * @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 * 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: * Example:
* *
* $messages = array( * $messages = array(
* 'post' => _n_noop( '%s post', '%s posts' ), * 'post' => _n_noop( '%s post', '%s posts', 'text-domain' ),
* 'page' => _n_noop( '%s pages', '%s pages' ), * 'page' => _n_noop( '%s pages', '%s pages', 'text-domain' ),
* ); * );
* ... * ...
* $message = $messages[ $type ]; * $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 * @since 2.5.0
* *
* @param string $singular Single form to be i18ned. * @param string $singular Singular form to be localized.
* @param string $plural Plural form to be i18ned. * @param string $plural Plural form to be localized.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. * @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 ) { function _n_noop( $singular, $plural, $domain = null ) {
return array( 0 => $singular, 1 => $plural, 'singular' => $singular, 'plural' => $plural, 'context' => null, 'domain' => $domain ); 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 * @since 2.8.0
* @param string $singular *
* @param string $plural * @param string $singular Singular form to be localized.
* @param string $context * @param string $plural Plural form to be localized.
* @param string|null $domain * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
* @return array * 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 ) { function _nx_noop( $singular, $plural, $context, $domain = null ) {
return array( 0 => $singular, 1 => $plural, 2 => $context, 'singular' => $singular, 'plural' => $plural, 'context' => $context, 'domain' => $domain ); 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 * @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 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 int $count Number of objects.
* @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings. If $nooped_plural contains * @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. * @return string Either $single or $plural translated text.
*/ */
function translate_nooped_plural( $nooped_plural, $count, $domain = 'default' ) { function translate_nooped_plural( $nooped_plural, $count, $domain = 'default' ) {

2
wp-includes/version.php
View File

@ -4,7 +4,7 @@
* *
* @global string $wp_version * @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. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.