diff --git a/wp-includes/l10n.php b/wp-includes/l10n.php index 0a01cfb80c..b30fa417aa 100644 --- a/wp-includes/l10n.php +++ b/wp-includes/l10n.php @@ -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' ) { diff --git a/wp-includes/version.php b/wp-includes/version.php index df49039b63..524637d1e0 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -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.