WordPress.org

Make WordPress Core

Ticket #16750: l10n.diff

File l10n.diff, 20.3 KB (added by CharlesClarkson, 3 years ago)

Changes for Inline documentation in the l10n.php file.

  • l10n.php

     
    5252} 
    5353 
    5454/** 
    55  * Retrieves the translation of $text. If there is no translation, or 
    56  * the domain isn't loaded the original text is returned. 
     55 * Retrieves the translation of $text. If there is no translation, or the domain 
     56 * isn't loaded the original text is returned. 
    5757 * 
    58  * @see __() Don't use translate() directly, use __() 
     58 * @see __() Don't use translate() directly, use __(). 
     59 * 
    5960 * @since 2.2.0 
    60  * @uses apply_filters() Calls 'gettext' on domain translated text 
    61  *              with the untranslated text as second parameter. 
    6261 * 
     62 * @uses apply_filters() Calls 'gettext' on domain translated text with the 
     63 * untranslated text as second parameter. 
     64 * 
    6365 * @param string $text Text to translate. 
    64  * @param string $domain Domain to retrieve the translated text. 
    65  * @return string Translated text 
     66 * @param string $domain Optional. Unique identifier for retrieving translated 
     67 *  strings. 
     68 * @return string Translated text. 
    6669 */ 
    6770function translate( $text, $domain = 'default' ) { 
    6871        $translations = &get_translations_for_domain( $domain ); 
    6972        return apply_filters( 'gettext', $translations->translate( $text ), $text, $domain ); 
    7073} 
    7174 
     75/** 
     76 * Removes last item on a pipe delimited string. 
     77 * 
     78 * Meant for removing the last item in a string like: 'Role name|User role'. It 
     79 * will return* the original string if no pipe '|' characters are found in 
     80 * the string. 
     81 * 
     82 * @since 2.7.0 
     83 * 
     84 * @param string $strimg A pipe delimited string. 
     85 * @return string Either $string or everything before last pipe. 
     86 */ 
    7287function before_last_bar( $string ) { 
    7388        $last_bar = strrpos( $string, '|' ); 
    7489        if ( false == $last_bar ) 
     
    7792                return substr( $string, 0, $last_bar ); 
    7893} 
    7994 
     95/** 
     96 * Retrieves the translation of $text in the context defined in $context. If 
     97 * there is no translation, or the domain isn't loaded the original text is 
     98 * returned. 
     99 * 
     100 * @since 2.8.0 
     101 * @see translate() 
     102 * @see _x() 
     103 * 
     104 * @param string $text Text to translate. 
     105 * @param string $context Context information for the translators. 
     106 * @param string $domain Optional. Unique identifier for retrieving translated 
     107 *  strings. 
     108 * @return string Translated text. 
     109 */ 
    80110function translate_with_gettext_context( $text, $context, $domain = 'default' ) { 
    81111        $translations = &get_translations_for_domain( $domain ); 
    82112        return apply_filters( 'gettext_with_context', $translations->translate( $text, $context ), $text, $context, $domain ); 
     
    86116 * Retrieves the translation of $text. If there is no translation, or 
    87117 * the domain isn't loaded the original text is returned. 
    88118 * 
    89  * @see translate() An alias of translate() 
     119 * @see translate() An alias of translate(). 
    90120 * @since 2.1.0 
    91121 * 
    92  * @param string $text Text to translate 
    93  * @param string $domain Optional. Domain to retrieve the translated text 
    94  * @return string Translated text 
     122 * @param string $text Text to translate. 
     123 * @param string $domain Optional. Unique identifier for retrieving translated 
     124 *  strings. 
     125 * @return string Translated text. 
    95126 */ 
    96127function __( $text, $domain = 'default' ) { 
    97128        return translate( $text, $domain ); 
    98129} 
    99130 
    100131/** 
    101  * Retrieves the translation of $text and escapes it for safe use in an attribute. 
    102  * If there is no translation, or the domain isn't loaded the original text is returned. 
     132 * Retrieves the translation of $text and escapes it for safe use in an 
     133 * attribute. If there is no translation, or the domain isn't loaded the 
     134 * original text is returned. 
    103135 * 
    104  * @see translate() An alias of translate() 
     136 * @see translate() An alias of translate(). 
    105137 * @see esc_attr() 
    106138 * @since 2.8.0 
    107139 * 
    108  * @param string $text Text to translate 
    109  * @param string $domain Optional. Domain to retrieve the translated text 
    110  * @return string Translated text 
     140 * @param string $text Text to translate. 
     141 * @param string $domain Optional. Unique identifier for retrieving translated 
     142 *  strings. 
     143 * @return string Translated text. 
    111144 */ 
    112145function esc_attr__( $text, $domain = 'default' ) { 
    113146        return esc_attr( translate( $text, $domain ) ); 
    114147} 
    115148 
    116149/** 
    117  * Retrieves the translation of $text and escapes it for safe use in HTML output. 
    118  * If there is no translation, or the domain isn't loaded the original text is returned. 
     150 * Retrieves the translation of $text and escapes it for safe use in HTML 
     151 * output. If there is no translation, or the domain isn't loaded the original 
     152 * text is returned. 
    119153 * 
    120  * @see translate() An alias of translate() 
     154 * @see translate() An alias of translate(). 
    121155 * @see esc_html() 
    122156 * @since 2.8.0 
    123157 * 
    124158 * @param string $text Text to translate 
    125  * @param string $domain Optional. Domain to retrieve the translated text 
     159 * @param string $domain Optional. Unique identifier for retrieving translated 
     160 *  strings. 
    126161 * @return string Translated text 
    127162 */ 
    128163function esc_html__( $text, $domain = 'default' ) { 
     
    132167/** 
    133168 * Displays the returned translated text from translate(). 
    134169 * 
    135  * @see translate() Echoes returned translate() string 
     170 * @see translate() Echoes returned translate() string. 
    136171 * @since 1.2.0 
    137172 * 
    138  * @param string $text Text to translate 
    139  * @param string $domain Optional. Domain to retrieve the translated text 
     173 * @param string $text Text to translate. 
     174 * @param string $domain Optional. Unique identifier for retrieving translated 
     175 *  strings. 
    140176 */ 
    141177function _e( $text, $domain = 'default' ) { 
    142178        echo translate( $text, $domain ); 
     
    145181/** 
    146182 * Displays translated text that has been escaped for safe use in an attribute. 
    147183 * 
    148  * @see translate() Echoes returned translate() string 
     184 * @see translate() Echoes returned translate() string. 
    149185 * @see esc_attr() 
    150186 * @since 2.8.0 
    151187 * 
    152  * @param string $text Text to translate 
    153  * @param string $domain Optional. Domain to retrieve the translated text 
     188 * @param string $text Text to translate. 
     189 * @param string $domain Optional. Unique identifier for retrieving translated 
     190 *  strings. 
    154191 */ 
    155192function esc_attr_e( $text, $domain = 'default' ) { 
    156193        echo esc_attr( translate( $text, $domain ) ); 
     
    159196/** 
    160197 * Displays translated text that has been escaped for safe use in HTML output. 
    161198 * 
    162  * @see translate() Echoes returned translate() string 
     199 * @see translate() Echoes returned translate() string. 
    163200 * @see esc_html() 
    164201 * @since 2.8.0 
    165202 * 
    166  * @param string $text Text to translate 
    167  * @param string $domain Optional. Domain to retrieve the translated text 
     203 * @param string $text Text to translate. 
     204 * @param string $domain Optional. Unique identifier for retrieving translated 
     205 *  strings. 
    168206 */ 
    169207function esc_html_e( $text, $domain = 'default' ) { 
    170208        echo esc_html( translate( $text, $domain ) ); 
    171209} 
    172210 
    173211/** 
    174  * Retrieve translated string with gettext context 
     212 * Retrieve translated string with gettext context. 
    175213 * 
    176214 * Quite a few times, there will be collisions with similar translatable text 
    177215 * found in more than two places but with different translated context. 
     
    181219 * 
    182220 * @since 2.8.0 
    183221 * 
    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 
     222 * @param string $text Text to translate. 
     223 * @param string $context Context information for the translators. 
     224 * @param string $domain Optional. Unique identifier for retrieving translated 
     225 *  strings. 
     226 * @return string Translated text. 
    188227 */ 
    189228function _x( $single, $context, $domain = 'default' ) { 
    190229        return translate_with_gettext_context( $single, $context, $domain ); 
    191230} 
    192231 
    193232/** 
    194  * Displays translated string with gettext context 
     233 * Displays translated string with gettext context. 
    195234 * 
    196235 * @see _x 
    197236 * @since 3.0.0 
    198237 * 
    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 
     238 * @param string $single Text to translate. 
     239 * @param string $context Context information for the translators. 
     240 * @param string $domain Optional. Unique identifier for retrieving translated 
     241 *  strings. 
     242 * @return string Translated text. 
    203243 */ 
    204244function _ex( $single, $context, $domain = 'default' ) { 
    205245        echo _x( $single, $context, $domain ); 
    206246} 
    207247 
     248/** 
     249 * Displays translated string with gettext context after escaping for HTML. 
     250 * 
     251 * @see translate() An alias of translate(). 
     252 * @see esc_attr() 
     253 * 
     254 * @since 3.0.0 
     255 * 
     256 * @param string $single Text to translate. 
     257 * @param string $context Context information for the translators. 
     258 * @param string $domain Optional. Unique identifier for retrieving translated 
     259 *  strings. 
     260 * @return string Translated text. 
     261 */ 
    208262function esc_attr_x( $single, $context, $domain = 'default' ) { 
    209263        return esc_attr( translate_with_gettext_context( $single, $context, $domain ) ); 
    210264} 
    211265 
     266/** 
     267 * Displays translated string with gettext context after escaping for HTML 
     268 * attributes. 
     269 * 
     270 * @see translate() An alias of translate(). 
     271 * @see esc_html() 
     272 * 
     273 * @since 3.0.0 
     274 * 
     275 * @param string $single Text to translate. 
     276 * @param string $context Context information for the translators. 
     277 * @param string $domain Optional. Unique identifier for retrieving translated 
     278 *  strings. 
     279 * @return string Translated text. 
     280 */ 
    212281function esc_html_x( $single, $context, $domain = 'default' ) { 
    213282        return esc_html( translate_with_gettext_context( $single, $context, $domain ) ); 
    214283} 
     
    226295 * 
    227296 * @since 2.8.0 
    228297 * @uses $l10n Gets list of domain translated string (gettext_reader) objects 
    229  * @uses apply_filters() Calls 'ngettext' hook on domains text returned, 
    230  *              along with $single, $plural, and $number parameters. Expected to return string. 
     298 * @uses apply_filters() Calls 'ngettext' hook on domains text returned, along 
     299 *  with $single, $plural, and $number parameters. Expected to return string. 
    231300 * 
    232  * @param string $single The text that will be used if $number is 1 
    233  * @param string $plural The text that will be used if $number is not 1 
    234  * @param int $number The number to compare against to use either $single or $plural 
    235  * @param string $domain Optional. The domain identifier the text should be retrieved in 
     301 * @param string $single The text that will be used if $number is 1. 
     302 * @param string $plural The text that will be used if $number is not 1. 
     303 * @param int $number 1 for $single, plural otherwise. 
     304 * @param string $domain Optional. Unique identifier for retrieving translated 
     305 *  strings. 
    236306 * @return string Either $single or $plural translated text 
    237307 */ 
    238308function _n( $single, $plural, $number, $domain = 'default' ) { 
     
    247317 * @see _n() 
    248318 * @see _x() 
    249319 * 
     320 * @since 2.8.0 
     321 * 
     322 * @param string $single The text that will be used if $number is 1. 
     323 * @param string $plural The text that will be used if $number is not 1. 
     324 * @param int $number 1 for $single, plural otherwise. 
     325 * @param string $context Context information for the translators. 
     326 * @param string $domain Optional. Unique identifier for retrieving translated 
     327 *  strings. 
     328 * @return string Either $single or $plural translated text. 
    250329 */ 
    251330function _nx($single, $plural, $number, $context, $domain = 'default') { 
    252331        $translations = &get_translations_for_domain( $domain ); 
     
    269348 *  $message = $messages[$type]; 
    270349 *  $usable_text = sprintf( translate_nooped_plural( $message, $count ), $count ); 
    271350 * 
     351 * @see _nx_noop() 
    272352 * @since 2.5 
    273  * @param string $single Single form to be i18ned 
    274  * @param string $plural Plural form to be i18ned 
    275  * @return array array($single, $plural) 
     353 * 
     354 * @param string $singular singular form to be i18ned. 
     355 * @param string $plural Plural form to be i18ned. 
     356 * @return array array( $single, $plural ). 
    276357 */ 
    277358function _n_noop( $singular, $plural ) { 
    278359        return array( 0 => $singular, 1 => $plural, 'singular' => $singular, 'plural' => $plural, 'context' => null ); 
     
    282363 * Register plural strings with context in POT file, but don't translate them. 
    283364 * 
    284365 * @see _n_noop() 
     366 * @since 2.5 
     367 * 
     368 * @param string $singular singular form to be i18ned. 
     369 * @param string $plural Plural form to be i18ned. 
     370 * @param string $context Context information for the translators. 
     371 * @return array array( $single, $plural ). 
    285372 */ 
    286373function _nx_noop( $singular, $plural, $context ) { 
    287374        return array( 0 => $singular, 1 => $plural, 2 => $context, 'singular' => $singular, 'plural' => $plural, 'context' => $context ); 
     
    291378 * Translate the result of _n_noop() or _nx_noop() 
    292379 * 
    293380 * @since 3.1 
    294  * @param array $nooped_plural array with singular, plural and context keys, usually the result of _n_noop() or _nx_noop() 
    295  * @param int $count number of objects 
    296  * @param string $domain Optional. The domain identifier the text should be retrieved in 
     381 * 
     382 * @param array $nooped_plural array with singular, plural and context keys, 
     383 *  usually the result of _n_noop() or _nx_noop(). 
     384 * @param int $count Number of objects. 
     385 * @param string $domain Optional. Unique identifier for retrieving translated 
     386 *  strings. 
     387 * @return string Either $nooped_plural['singular'] or $nooped_plural['plural'] 
     388 *  translated text. 
    297389 */ 
    298390function translate_nooped_plural( $nooped_plural, $count, $domain = 'default' ) { 
    299391        if ( $nooped_plural['context'] ) 
     
    305397/** 
    306398 * Loads a MO file into the domain $domain. 
    307399 * 
    308  * If the domain already exists, the translations will be merged. If both 
    309  * sets have the same string, the translation from the original value will be taken. 
     400 * If the domain already exists, the translations will be merged. If both sets 
     401 * have the same string, the translation from the original value will be taken. 
    310402 * 
    311  * On success, the .mo file will be placed in the $l10n global by $domain 
    312  * and will be a MO object. 
     403 * On success, the .mo file will be placed in the $l10n global by $domain and 
     404 * will be a MO object. 
    313405 * 
    314406 * @since 1.5.0 
    315  * @uses $l10n Gets list of domain translated string objects 
     407 * @uses $l10n Gets list of domain translated string objects. 
    316408 * 
    317  * @param string $domain Unique identifier for retrieving translated strings 
    318  * @param string $mofile Path to the .mo file 
    319  * @return bool true on success, false on failure 
     409 * @param string $domain Unique identifier for retrieving translated  strings. 
     410 * @param string $mofile Path to the .mo file. 
     411 * @return bool true on success, false on failure. 
    320412 */ 
    321413function load_textdomain( $domain, $mofile ) { 
    322414        global $l10n; 
     
    345437} 
    346438 
    347439/** 
    348  * Unloads translations for a domain 
     440 * Unloads translations for a domain. 
    349441 * 
    350442 * @since 3.0.0 
    351  * @param string $domain Textdomain to be unloaded 
    352  * @return bool Whether textdomain was unloaded 
     443 * 
     444 * @param string $domain Text domain to be unloaded. 
     445 * @return bool Whether text domain was unloaded. 
    353446 */ 
    354447function unload_textdomain( $domain ) { 
    355448        global $l10n; 
     
    391484 * Loads the plugin's translated strings. 
    392485 * 
    393486 * If the path is not given then it will be the root of the plugin directory. 
    394  * The .mo file should be named based on the domain with a dash, and then the locale exactly. 
     487 * The .mo file should be named based on the domain with a dash, and then the 
     488 * locale exactly. 
    395489 * 
    396490 * @since 1.5.0 
    397491 * 
    398  * @param string $domain Unique identifier for retrieving translated strings 
     492 * @param string $domain Unique identifier for retrieving translated strings. 
    399493 * @param string $abs_rel_path Optional. Relative path to ABSPATH of a folder, 
    400  *      where the .mo file resides. Deprecated, but still functional until 2.7 
    401  * @param string $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR. This is the preferred argument to use. It takes precendence over $abs_rel_path 
     494 *      where the .mo file resides. Deprecated, but still functional until 2.7. 
     495 * @param string $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR. 
     496 *  This is the preferred argument to use. It takes precendence over $abs_rel_path. 
     497 * @return bool true on success, false on failure. 
    402498 */ 
    403499function load_plugin_textdomain( $domain, $abs_rel_path = false, $plugin_rel_path = false ) { 
    404500        $locale = apply_filters( 'plugin_locale', get_locale(), $domain ); 
     
    421517 * 
    422518 * @since 3.0.0 
    423519 * 
    424  * @param string $domain Unique identifier for retrieving translated strings 
    425  * @param strings $mu_plugin_rel_path Relative to WPMU_PLUGIN_DIR directory in which 
    426  * the MO file resides. Defaults is empty string. 
     520 * @param string $domain Unique identifier for retrieving translated strings. 
     521 * @param strings $mu_plugin_rel_path Relative to WPMU_PLUGIN_DIR directory in 
     522 *  which * the MO file resides. Defaults is empty string. 
     523 * @return bool true on success, false on failure. 
    427524 */ 
    428525function load_muplugin_textdomain( $domain, $mu_plugin_rel_path = '' ) { 
    429526        $locale = apply_filters( 'plugin_locale', get_locale(), $domain ); 
     
    441538 * 
    442539 * @since 1.5.0 
    443540 * 
    444  * @param string $domain Unique identifier for retrieving translated strings 
     541 * @param string $domain Unique identifier for retrieving translated strings. 
     542 * @return bool true on success, false on failure. 
    445543 */ 
    446544function load_theme_textdomain( $domain, $path = false ) { 
    447545        $locale = apply_filters( 'theme_locale', get_locale(), $domain ); 
     
    455553/** 
    456554 * Loads the child themes translated strings. 
    457555 * 
    458  * If the current locale exists as a .mo file in the child themes root directory, it 
    459  * will be included in the translated strings by the $domain. 
     556 * If the current locale exists as a .mo file in the child themes root 
     557 * directory, it will be included in the translated strings by the $domain. 
    460558 * 
    461559 * The .mo files must be named based on the locale exactly. 
    462560 * 
    463561 * @since 2.9.0 
    464562 * 
    465  * @param string $domain Unique identifier for retrieving translated strings 
     563 * @param string $domain Unique identifier for retrieving translated strings. 
     564 * @param string|bool $path Optional. Path to chlid theme directory of false. 
     565 * @return bool true on success, false on failure. 
    466566 */ 
    467567function load_child_theme_textdomain( $domain, $path = false ) { 
    468568        $locale = apply_filters( 'theme_locale', get_locale(), $domain ); 
     
    477577 * Returns the Translations instance for a domain. If there isn't one, 
    478578 * returns empty Translations instance. 
    479579 * 
    480  * @param string $domain 
    481  * @return object A Translation instance 
     580 * @see NOOP_Translations class. 
     581 * 
     582 * @since 3.0.0 
     583 * 
     584 * @param string $domain Unique identifier for retrieving translated strings. 
     585 * @return object A Translation instance. 
    482586 */ 
    483587function &get_translations_for_domain( $domain ) { 
    484588        global $l10n; 
     
    489593} 
    490594 
    491595/** 
    492  * Whether there are translations for the domain 
     596 * Whether there are translations for the domain. 
    493597 * 
    494598 * @since 3.0.0 
    495  * @param string $domain 
    496  * @return bool Whether there are translations 
     599 * 
     600 * @param string $domain Unique identifier for retrieving translated strings. 
     601 * @return bool Whether there are translations. 
    497602 */ 
    498603function is_textdomain_loaded( $domain ) { 
    499604        global $l10n; 
     
    509614 * using the old context format: 'Role name|User role' and just skipping the 
    510615 * content after the last bar is easier than fixing them in the DB. New installs 
    511616 * won't suffer from that problem. 
     617 * 
     618 * @since 2.8.0 
     619 * 
     620 * @param string $name A pipe delimited string. 
     621 * @return string Translated text. 
    512622 */ 
    513623function translate_user_role( $name ) { 
    514624        return translate_with_gettext_context( before_last_bar($name), 'User role' ); 
    515625} 
    516626 
    517627/** 
    518  * Get all available languages based on the presence of *.mo files in a given directory. The default directory is WP_LANG_DIR. 
     628 * Get all available languages based on the presence of *.mo files in a given 
     629 * directory. The default directory is WP_LANG_DIR. 
    519630 * 
    520631 * @since 3.0.0 
    521632 * 
    522  * @param string $dir A directory in which to search for language files. The default directory is WP_LANG_DIR. 
    523  * @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. 
     633 * @param string $dir A directory in which to search for language files. The 
     634 *  default directory is WP_LANG_DIR. 
     635 * @return array Array of language codes or an empty array if no languages are 
     636 *  present. Language codes are formed by stripping the .mo extension from the 
     637 *  language file names. 
    524638 */ 
    525639function get_available_languages( $dir = null ) { 
    526640        $languages = array(); 
     
    532646        } 
    533647 
    534648        return $languages; 
    535 } 
    536  No newline at end of file 
     649}