WordPress.org
Get WordPress

Make WordPress Core

Changeset 25458


Ignore:
Timestamp:
09/16/2013 08:16:58 PM (11 years ago)
Author:
SergeyBiryukov
Message:

Update inline documentation for l10n functions. props CharlesClarkson, DrewAPicture. fixes #16750.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r25085 r25458  
    88
    99/**
    10  * Gets the current locale.
     10 * Get the current locale.
    1111 *
    1212 * If the locale is set, then it will filter the locale in the 'locale' filter
    … …  
    2121 *
    2222 * @since 1.5.0
    23  * @uses apply_filters() Calls 'locale' hook on locale value.
    24  * @uses $locale Gets the locale stored in the global.
    2523 *
    2624 * @return string The locale of the blog or from the 'locale' hook.
    … …  
    5351
    5452/**
    55  * Retrieves the translation of $text. If there is no translation, or
    56  * the domain isn't loaded, the original text is returned.
    57  *
    58  * @see __() Don't use translate() directly, use __()
     53 * Retrieve the translation of $text.
     54 *
     55 * If there is no translation, or the domain isn't loaded, the original text is returned.
     56 *
     57 * <strong>Note:</strong> Don't use translate() directly, use __() or related functions.
     58 *
    5959 * @since 2.2.0
    60  * @uses apply_filters() Calls 'gettext' on domain translated text
    61  *      with the untranslated text as second parameter.
    62  *
    63  * @param string $text Text to translate.
    64  * @param string $domain Domain to retrieve the translated text.
     60 *
     61 * @param string $text   Text to translate.
     62 * @param string $domain Optional. Unique identifier for retrieving translated strings.
    6563 * @return string Translated text
    6664 */
    … …  
    7068}
    7169
     70/**
     71 * Remove last item on a pipe-delimited string.
     72 *
     73 * Meant for removing the last item in a string, such as 'Role name|User role'. The original
     74 * string will be returned if no pipe '|' characters are found in the string.
     75 *
     76 * @since 2.8.0
     77 *
     78 * @param string $string A pipe-delimited string.
     79 * @return string Either $string or everything before the last pipe.
     80 */
    7281function before_last_bar( $string ) {
    7382    $last_bar = strrpos( $string, '|' );
    … …  
    7887}
    7988
     89/**
     90 * Retrieve the translation of $text in the context defined in $context.
     91 *
     92 * If there is no translation, or the domain isn't loaded the original
     93 * text is returned.
     94 *
     95 * @since 2.8.0
     96 *
     97 * @param string $text    Text to translate.
     98 * @param string $context Context information for the translators.
     99 * @param string $domain  Optional. Unique identifier for retrieving translated strings.
     100 * @return string Translated text on success, original text on failure.
     101 */
    80102function translate_with_gettext_context( $text, $context, $domain = 'default' ) {
    81103    $translations = get_translations_for_domain( $domain );
    … …  
    84106
    85107/**
    86  * Retrieves the translation of $text. If there is no translation, or
    87  * the domain isn't loaded, the original text is returned.
    88  *
    89  * @see translate() An alias of translate()
     108 * Retrieve the translation of $text. If there is no translation,
     109 * or the domain isn't loaded, the original text is returned.
     110 *
    90111 * @since 2.1.0
    91112 *
    92  * @param string $text Text to translate
    93  * @param string $domain Optional. Domain to retrieve the translated text
    94  * @return string Translated text
     113 * @param string $text   Text to translate.
     114 * @param string $domain Optional. Unique identifier for retrieving translated strings.
     115 * @return string Translated text.
    95116 */
    96117function __( $text, $domain = 'default' ) {
    … …  
    99120
    100121/**
    101  * Retrieves the translation of $text and escapes it for safe use in an attribute.
     122 * Retrieve the translation of $text and escapes it for safe use in an attribute.
     123 *
    102124 * If there is no translation, or the domain isn't loaded, the original text is returned.
    103125 *
    104  * @see translate() An alias of translate()
    105  * @see esc_attr()
    106  * @since 2.8.0
    107  *
    108  * @param string $text Text to translate
    109  * @param string $domain Optional. Domain to retrieve the translated text
    110  * @return string Translated text
     126 * @since 2.8.0
     127 *
     128 * @param string $text   Text to translate.
     129 * @param string $domain Optional. Unique identifier for retrieving translated strings.
     130 * @return string Translated text on success, original text on failure.
    111131 */
    112132function esc_attr__( $text, $domain = 'default' ) {
    … …  
    115135
    116136/**
    117  * Retrieves the translation of $text and escapes it for safe use in HTML output.
     137 * Retrieve the translation of $text and escapes it for safe use in HTML output.
     138 *
    118139 * If there is no translation, or the domain isn't loaded, the original text is returned.
    119140 *
    120  * @see translate() An alias of translate()
    121  * @see esc_html()
    122  * @since 2.8.0
    123  *
    124  * @param string $text Text to translate
    125  * @param string $domain Optional. Domain to retrieve the translated text
     141 * @since 2.8.0
     142 *
     143 * @param string $text   Text to translate.
     144 * @param string $domain Optional. Unique identifier for retrieving translated strings.
    126145 * @return string Translated text
    127146 */
    … …  
    131150
    132151/**
    133  * Displays the returned translated text from translate().
    134  *
    135  * @see translate() Echoes returned translate() string
     152 * Display translated text.
     153 *
    136154 * @since 1.2.0
    137155 *
    138  * @param string $text Text to translate
    139  * @param string $domain Optional. Domain to retrieve the translated text
     156 * @param string $text   Text to translate.
     157 * @param string $domain Optional. Unique identifier for retrieving translated strings.
    140158 */
    141159function _e( $text, $domain = 'default' ) {
    … …  
    144162
    145163/**
    146  * Displays translated text that has been escaped for safe use in an attribute.
    147  *
    148  * @see translate() Echoes returned translate() string
    149  * @see esc_attr()
    150  * @since 2.8.0
    151  *
    152  * @param string $text Text to translate
    153  * @param string $domain Optional. Domain to retrieve the translated text
     164 * Display translated text that has been escaped for safe use in an attribute.
     165 *
     166 * @since 2.8.0
     167 *
     168 * @param string $text   Text to translate.
     169 * @param string $domain Optional. Unique identifier for retrieving translated strings.
    154170 */
    155171function esc_attr_e( $text, $domain = 'default' ) {
    … …  
    158174
    159175/**
    160  * Displays translated text that has been escaped for safe use in HTML output.
    161  *
    162  * @see translate() Echoes returned translate() string
    163  * @see esc_html()
    164  * @since 2.8.0
    165  *
    166  * @param string $text Text to translate
    167  * @param string $domain Optional. Domain to retrieve the translated text
     176 * Display translated text that has been escaped for safe use in HTML output.
     177 *
     178 * @since 2.8.0
     179 *
     180 * @param string $text   Text to translate.
     181 * @param string $domain Optional. Unique identifier for retrieving translated strings.
    168182 */
    169183function esc_html_e( $text, $domain = 'default' ) {
    … …  
    172186
    173187/**
    174  * Retrieve translated string with gettext context
     188 * Retrieve translated string with gettext context.
    175189 *
    176190 * Quite a few times, there will be collisions with similar translatable text
    177  * found in more than two places but with different translated context.
    178  *
    179  * By including the context in the pot file translators can translate the two
     191 * found in more than two places, but with different translated context.
     192 *
     193 * By including the context in the pot file, translators can translate the two
    180194 * strings differently.
    181195 *
    182196 * @since 2.8.0
    183197 *
    184  * @param string $text Text to translate
    185  * @param string $context Context information for the translators
    186  * @param string $domain Optional. Domain to retrieve the translated text
    187  * @return string Translated context string without pipe
     198 * @param string $text    Text to translate.
     199 * @param string $context Context information for the translators.
     200 * @param string $domain  Optional. Unique identifier for retrieving translated strings.
     201 * @return string Translated context string without pipe.
    188202 */
    189203function _x( $text, $context, $domain = 'default' ) {
    … …  
    192206
    193207/**
    194  * Displays translated string with gettext context
    195  *
    196  * @see _x
     208 * Display translated string with gettext context.
     209 *
    197210 * @since 3.0.0
    198211 *
    199  * @param string $text Text to translate
    200  * @param string $context Context information for the translators
    201  * @param string $domain Optional. Domain to retrieve the translated text
    202  * @return string Translated context string without pipe
     212 * @param string $text    Text to translate.
     213 * @param string $context Context information for the translators.
     214 * @param string $domain  Optional. Unique identifier for retrieving translated strings.
     215 * @return string Translated context string without pipe.
    203216 */
    204217function _ex( $text, $context, $domain = 'default' ) {
    … …  
    207220
    208221/**
    209  * Displays translated string with gettext context and escapes it for safe use in an attribute.
    210  *
    211  * @see esc_attr()
    212  * @since 2.8.0
    213  *
    214  * @param string $text Text to translate
    215  * @param string $context Context information for the translators
    216  * @param string $domain Optional. Domain to retrieve the translated text
     222 * Display translated string with gettext context, and escapes it for safe use in an attribute.
     223 *
     224 * @since 2.8.0
     225 *
     226 * @param string $text    Text to translate.
     227 * @param string $context Context information for the translators.
     228 * @param string $domain  Optional. Unique identifier for retrieving translated strings.
    217229 * @return string Translated text
    218230 */
    … …  
    222234
    223235/**
    224  * Displays translated string with gettext context and escapes it for safe use in HTML output.
    225  *
    226  * @see esc_html()
     236 * Display translated string with gettext context, and escapes it for safe use in HTML output.
     237 *
    227238 * @since 2.9.0
    228239 *
    229  * @param string $text Text to translate
    230  * @param string $context Context information for the translators
    231  * @param string $domain Optional. Domain to retrieve the translated text
    232  * @return string Translated text
     240 * @param string $text    Text to translate.
     241 * @param string $context Context information for the translators.
     242 * @param string $domain  Optional. Unique identifier for retrieving translated strings.
     243 * @return string Translated text.
    233244 */
    234245function esc_html_x( $text, $context, $domain = 'default' ) {
    … …  
    237248
    238249/**
    239  * Retrieve the plural or single form based on the amount.
     250 * Retrieve the plural or single form based on the supplied amount.
    240251 *
    241252 * If the domain is not set in the $l10n list, then a comparison will be made
    … …  
    248259 *
    249260 * @since 2.8.0
    250  * @uses $l10n Gets list of domain translated string (gettext_reader) objects
    251  * @uses apply_filters() Calls 'ngettext' hook on domains text returned,
    252  *      along with $single, $plural, and $number parameters. Expected to return string.
    253  *
    254  * @param string $single The text that will be used if $number is 1
    255  * @param string $plural The text that will be used if $number is not 1
    256  * @param int $number The number to compare against to use either $single or $plural
    257  * @param string $domain Optional. The domain identifier the text should be retrieved in
    258  * @return string Either $single or $plural translated text
     261 *
     262 * @param string $single The text that will be used if $number is 1.
     263 * @param string $plural The text that will be used if $number is not 1.
     264 * @param int    $number The number to compare against to use either $single or $plural.
     265 * @param string $domain Optional. Unique identifier for retrieving translated strings.
     266 * @return string Either $single or $plural translated text.
    259267 */
    260268function _n( $single, $plural, $number, $domain = 'default' ) {
    … …  
    265273
    266274/**
    267  * A hybrid of _n() and _x(). It supports contexts and plurals.
    268  *
    269  * @see _n()
    270  * @see _x()
    271  *
     275 * Retrieve the plural or single form based on the supplied amount with gettext context.
     276 *
     277 * This is a hybrid of _n() and _x(). It supports contexts and plurals.
     278 *
     279 * @since 2.8.0
     280 *
     281 * @param string $single  The text that will be used if $number is 1.
     282 * @param string $plural  The text that will be used if $number is not 1.
     283 * @param int    $number  The number to compare against to use either $single or $plural.
     284 * @param string $context Context information for the translators.
     285 * @param string $domain  Optional. Unique identifier for retrieving translated strings.
     286 * @return string Either $single or $plural translated text with context.
    272287 */
    273288function _nx($single, $plural, $number, $context, $domain = 'default') {
    … …  
    280295 * Register plural strings in POT file, but don't translate them.
    281296 *
    282  * Used when you want to keep structures with translatable plural strings and
    283  * use them later.
     297 * Used when you want to keep structures with translatable plural
     298 * strings and use them later.
    284299 *
    285300 * Example:
    286  *  $messages = array(
     301 * <code>
     302 * $messages = array(
    287303 *      'post' => _n_noop('%s post', '%s posts'),
    288304 *      'page' => _n_noop('%s pages', '%s pages')
    289  *  );
    290  *  ...
    291  *  $message = $messages[$type];
    292  *  $usable_text = sprintf( translate_nooped_plural( $message, $count ), $count );
    293  *
    294  * @since 2.5
    295  * @param string $singular Single form to be i18ned
    296  * @param string $plural Plural form to be i18ned
    297  * @param string $domain Optional. The domain identifier the text will be retrieved in
     305 * );
     306 * ...
     307 * $message = $messages[$type];
     308 * $usable_text = sprintf( translate_nooped_plural( $message, $count ), $count );
     309 * </code>
     310 *
     311 * @since 2.5.0
     312 *
     313 * @param string $singular Single form to be i18ned.
     314 * @param string $plural   Plural form to be i18ned.
     315 * @param string $domain   Optional. Unique identifier for retrieving translated strings.
    298316 * @return array array($singular, $plural)
    299317 */
    … …  
    305323 * Register plural strings with context in POT file, but don't translate them.
    306324 *
    307  * @see _n_noop()
     325 * @since 2.8.0
    308326 */
    309327function _nx_noop( $singular, $plural, $context, $domain = null ) {
    … …  
    312330
    313331/**
    314  * Translate the result of _n_noop() or _nx_noop()
    315  *
    316  * @since 3.1
    317  * @param array $nooped_plural Array with singular, plural and context keys, usually the result of _n_noop() or _nx_noop()
    318  * @param int $count Number of objects
    319  * @param string $domain Optional. The domain identifier the text should be retrieved in. If $nooped_plural contains
    320  *  a domain passed to _n_noop() or _nx_noop(), it will override this value.
     332 * Translate the result of _n_noop() or _nx_noop().
     333 *
     334 * @since 3.1.0
     335 *
     336 * @param array  $nooped_plural Array with singular, plural and context keys, usually the result of _n_noop() or _nx_noop()
     337 * @param int    $count         Number of objects
     338 * @param string $domain        Optional. Unique identifier for retrieving translated strings. If $nooped_plural contains
     339 *                              a domain passed to _n_noop() or _nx_noop(), it will override this value.
     340 * @return string Either $single or $plural translated text.
    321341 */
    322342function translate_nooped_plural( $nooped_plural, $count, $domain = 'default' ) {
    … …  
    331351
    332352/**
    333  * Loads a MO file into the domain $domain.
     353 * Load a .mo file into the domain $domain.
    334354 *
    335355 * If the domain already exists, the translations will be merged. If both
    … …  
    340360 *
    341361 * @since 1.5.0
    342  * @uses $l10n Gets list of domain translated string objects
    343  *
    344  * @param string $domain Unique identifier for retrieving translated strings
    345  * @param string $mofile Path to the .mo file
    346  * @return bool True on success, false on failure
     362 *
     363 * @param string $domain Unique identifier for retrieving translated strings.
     364 * @param string $mofile Path to the .mo file.
     365 * @return bool True on success, false on failure.
    347366 */
    348367function load_textdomain( $domain, $mofile ) {
    … …  
    373392
    374393/**
    375  * Unloads translations for a domain
     394 * Unload translations for a domain.
    376395 *
    377396 * @since 3.0.0
    378  * @param string $domain Textdomain to be unloaded
    379  * @return bool Whether textdomain was unloaded
     397 *
     398 * @param string $domain Unique identifier for retrieving translated strings.
     399 * @return bool Whether textdomain was unloaded.
    380400 */
    381401function unload_textdomain( $domain ) {
    … …  
    398418
    399419/**
    400  * Loads default translated strings based on locale.
    401  *
    402  * Loads the .mo file in WP_LANG_DIR constant path from WordPress root. The
    403  * translated (.mo) file is named based on the locale.
     420 * Load default translated strings based on locale.
     421 *
     422 * Loads the .mo file in WP_LANG_DIR constant path from WordPress root.
     423 * The translated (.mo) file is named based on the locale.
     424 *
     425 * @see load_textdomain()
    404426 *
    405427 * @since 1.5.0
    … …  
    424446
    425447/**
    426  * Loads the plugin's translated strings.
     448 * Load a plugin's translated strings.
    427449 *
    428450 * If the path is not given then it will be the root of the plugin directory.
     451 *
    429452 * The .mo file should be named based on the domain with a dash, and then the locale exactly.
    430453 *
    431454 * @since 1.5.0
    432455 *
    433  * @param string $domain Unique identifier for retrieving translated strings
    434  * @param string $abs_rel_path Optional. Relative path to ABSPATH of a folder,
    435  *  where the .mo file resides. Deprecated, but still functional until 2.7
    436  * @param string $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR. This is the preferred argument to use. It takes precedence over $abs_rel_path
    437  */
    438 function load_plugin_textdomain( $domain, $abs_rel_path = false, $plugin_rel_path = false ) {
     456 * @param string $domain          Unique identifier for retrieving translated strings
     457 * @param string $deprecated      Use the $plugin_rel_path parameter instead.
     458 * @param string $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR where the .mo file resides.
     459 */
     460function load_plugin_textdomain( $domain, $deprecated = false, $plugin_rel_path = false ) {
    439461    $locale = apply_filters( 'plugin_locale', get_locale(), $domain );
    440462
    441463    if ( false !== $plugin_rel_path ) {
    442464        $path = WP_PLUGIN_DIR . '/' . trim( $plugin_rel_path, '/' );
    443     } else if ( false !== $abs_rel_path ) {
     465    } else if ( false !== $deprecated ) {
    444466        _deprecated_argument( __FUNCTION__, '2.7' );
    445         $path = ABSPATH . trim( $abs_rel_path, '/' );
     467        $path = ABSPATH . trim( $deprecated, '/' );
    446468    } else {
    447469        $path = WP_PLUGIN_DIR;
    … …  
    459481
    460482/**
    461  * Load the translated strings for a plugin residing in the mu-plugins dir.
     483 * Load the translated strings for a plugin residing in the mu-plugins directory.
    462484 *
    463485 * @since 3.0.0
    464486 *
    465  * @param string $domain Unique identifier for retrieving translated strings
    466  * @param string $mu_plugin_rel_path Relative to WPMU_PLUGIN_DIR directory in which
    467  * the MO file resides. Defaults to empty string.
     487 * @param string $domain             Unique identifier for retrieving translated strings.
     488 * @param string $mu_plugin_rel_path Relative to WPMU_PLUGIN_DIR directory in which the .mo file resides.
     489 *                                   Default empty string.
     490 * @return bool True when textdomain is successfully loaded, false otherwise.
    468491 */
    469492function load_muplugin_textdomain( $domain, $mu_plugin_rel_path = '' ) {
    … …  
    482505
    483506/**
    484  * Loads the theme's translated strings.
     507 * Load the theme's translated strings.
    485508 *
    486509 * If the current locale exists as a .mo file in the theme's root directory, it
    … …  
    491514 * @since 1.5.0
    492515 *
    493  * @param string $domain Unique identifier for retrieving translated strings
     516 * @param string $domain Unique identifier for retrieving translated strings.
     517 * @return bool True when textdomain is successfully loaded, false otherwise.
    494518 */
    495519function load_theme_textdomain( $domain, $path = false ) {
    … …  
    510534
    511535/**
    512  * Loads the child themes translated strings.
    513  *
    514  * If the current locale exists as a .mo file in the child themes root directory, it
    515  * will be included in the translated strings by the $domain.
     536 * Load the child themes translated strings.
     537 *
     538 * If the current locale exists as a .mo file in the child themes
     539 * root directory, it will be included in the translated strings by the $domain.
    516540 *
    517541 * The .mo files must be named based on the locale exactly.
    … …  
    519543 * @since 2.9.0
    520544 *
    521  * @param string $domain Unique identifier for retrieving translated strings
     545 * @param string $domain Unique identifier for retrieving translated strings.
     546 * @return bool True when the theme textdomain is successfully loaded, false otherwise.
    522547 */
    523548function load_child_theme_textdomain( $domain, $path = false ) {
    … …  
    528553
    529554/**
    530  * Returns the Translations instance for a domain. If there isn't one,
    531  * returns empty Translations instance.
    532  *
    533  * @param string $domain
    534  * @return object A Translation instance
     555 * Return the Translations instance for a domain.
     556 *
     557 * If there isn't one, returns empty Translations instance.
     558 *
     559 * @param string $domain Unique identifier for retrieving translated strings.
     560 * @return Translations A Translations instance.
    535561 */
    536562function get_translations_for_domain( $domain ) {
    … …  
    546572 *
    547573 * @since 3.0.0
    548  * @param string $domain
    549  * @return bool Whether there are translations
     574 * @param string $domain Unique identifier for retrieving translated strings.
     575 * @return bool Whether there are translations.
    550576 */
    551577function is_textdomain_loaded( $domain ) {
    … …  
    555581
    556582/**
    557  * Translates role name. Since the role names are in the database and
    558  * not in the source there are dummy gettext calls to get them into the POT
    559  * file and this function properly translates them back.
     583 * Translates role name.
     584 *
     585 * Since the role names are in the database and not in the source there
     586 * are dummy gettext calls to get them into the POT file and this function
     587 * properly translates them back.
    560588 *
    561589 * The before_last_bar() call is needed, because older installs keep the roles
    … …  
    563591 * content after the last bar is easier than fixing them in the DB. New installs
    564592 * won't suffer from that problem.
     593 *
     594 * @since 2.8.0
     595 *
     596 * @param string $name The role name.
     597 * @return string Translated role name on success, original name on failure.
    565598 */
    566599function translate_user_role( $name ) {
    … …  
    569602
    570603/**
    571  * Get all available languages based on the presence of *.mo files in a given directory. The default directory is WP_LANG_DIR.
     604 * Get all available languages based on the presence of *.mo files in a given directory.
     605 *
     606 * The default directory is WP_LANG_DIR.
    572607 *
    573608 * @since 3.0.0
    574609 *
    575  * @param string $dir A directory in which to search for language files. The default directory is WP_LANG_DIR.
    576  * @return array Array of language codes or an empty array if no languages are present. Language codes are formed by stripping the .mo extension from the language file names.
     610 * @param string $dir A directory to search for language files.
     611 *                    Default WP_LANG_DIR.
     612 * @return array An array of language codes or an empty array if no languages are present. Language codes are formed by stripping the .mo extension from the language file names.
    577613 */
    578614function get_available_languages( $dir = null ) {
Note: See TracChangeset for help on using the changeset viewer.