WordPress.org
Get WordPress

Make WordPress Core

Ticket #16750: l10n.diff

File l10n.diff, 20.3 KB (added by CharlesClarkson, 15 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}