WordPress.org

Make WordPress Core

Changeset 6563


Ignore:
Timestamp:
01/06/2008 01:28:34 AM (12 years ago)
Author:
ryan
Message:

phpdoc for l10n. Props darkdragon. fixes #5590

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/l10n.php

    r6364 r6563  
    11<?php
     2/**
     3 * WordPress Translation API
     4 *
     5 * @package WordPress
     6 * @subpackage i18n
     7 */
     8
     9/**
     10 * get_locale() - Gets the current locale
     11 *
     12 * If the locale is set, then it will filter the locale
     13 * in the 'locale' filter hook and return the value.
     14 *
     15 * If the locale is not set already, then the WPLANG
     16 * constant is used if it is defined. Then it is filtered
     17 * through the 'locale' filter hook and the value for the
     18 * locale global set and the locale is returned.
     19 *
     20 * The process to get the locale should only be done once
     21 * but the locale will always be filtered using the
     22 * 'locale' hook.
     23 *
     24 * @since 1.5.0
     25 * @uses apply_filters() Calls 'locale' hook on locale value
     26 * @uses $locale Gets the locale stored in the global
     27 *
     28 * @return string The locale of the blog or from the 'locale' hook
     29 */
    230function get_locale() {
    331    global $locale;
     
    1846}
    1947
     48/**
     49 * translate() - Retrieve the translated text
     50 *
     51 * If the domain is set in the $l10n global, then the text is run
     52 * through the domain's translate method. After it is passed to
     53 * the 'gettext' filter hook, along with the untranslated text as
     54 * the second parameter.
     55 *
     56 * If the domain is not set, the the $text is just returned.
     57 *
     58 * @since 2.2.0
     59 * @uses $l10n Gets list of domain translated string (gettext_reader) objects
     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
     65 * @return string Translated text
     66 */
    2067function translate($text, $domain) {
    2168    global $l10n;
     
    2774}
    2875
    29 // Return a translated string.
     76/**
     77 * __() - Retrieve a translated string
     78 *
     79 * __() is a convenience function which retrieves the translated
     80 * string from the translate().
     81 *
     82 * @see translate() An alias of translate()
     83 * @since 2.1.0
     84 *
     85 * @param string $text Text to translate
     86 * @param string $domain Optional. Domain to retrieve the translated text
     87 * @return string Translated text
     88 */
    3089function __($text, $domain = 'default') {
    3190    return translate($text, $domain);
    3291}
    3392
    34 // Echo a translated string.
     93// .
     94/**
     95 * _e() - Display a translated string
     96 *
     97 * _e() is a convenience function which displays the returned
     98 * translated text from translate().
     99 *
     100 * @see translate() Echos returned translate() string
     101 * @since 1.2.0
     102 *
     103 * @param string $text Text to translate
     104 * @param string $domain Optional. Domain to retrieve the translated text
     105 */
    35106function _e($text, $domain = 'default') {
    36107    echo translate($text, $domain);
    37108}
    38109
     110/**
     111 * _c() - Retrieve context translated string
     112 *
     113 * Quite a few times, there will be collisions with similar
     114 * translatable text found in more than two places but with
     115 * different translated context.
     116 *
     117 * In order to use the separate contexts, the _c() function
     118 * is used and the translatable string uses a pipe ('|')
     119 * which has the context the string is in.
     120 *
     121 * When the translated string is returned, it is everything
     122 * before the pipe, not including the pipe character. If
     123 * there is no pipe in the translated text then everything
     124 * is returned.
     125 *
     126 * @since 2.2.0
     127 *
     128 * @param string $text Text to translate
     129 * @param string $domain Optional. Domain to retrieve the translated text
     130 * @return string Translated context string without pipe
     131 */
    39132function _c($text, $domain = 'default') {
    40133    $whole = translate($text, $domain);
     
    47140}
    48141
    49 // Return the plural form.
     142/**
     143 * __ngettext() - Retrieve the plural or single form based on the amount
     144 *
     145 * If the domain is not set in the $l10n list, then a comparsion
     146 * will be made and either $plural or $single parameters returned.
     147 *
     148 * If the domain does exist, then the parameters $single, $plural,
     149 * and $number will first be passed to the domain's ngettext method.
     150 * Then it will be passed to the 'ngettext' filter hook along with
     151 * the same parameters. The expected type will be a string.
     152 *
     153 * @since 1.2.0
     154 * @uses $l10n Gets list of domain translated string (gettext_reader) objects
     155 * @uses apply_filters() Calls 'ngettext' hook on domains text returned,
     156 *      along with $single, $plural, and $number parameters. Expected to return string.
     157 *
     158 * @param string $single The text that will be used if $number is 1
     159 * @param string $plural The text that will be used if $number is not 1
     160 * @param int $number The number to compare against to use either $single or $plural
     161 * @param string $domain Optional. The domain identifier the text should be retrieved in
     162 * @return string Either $single or $plural translated text
     163 */
    50164function __ngettext($single, $plural, $number, $domain = 'default') {
    51165    global $l10n;
     
    61175}
    62176
     177/**
     178 * load_textdomain() - Loads MO file into the list of domains
     179 *
     180 * If the domain already exists, the inclusion will fail. If the
     181 * MO file is not readable, the inclusion will fail.
     182 *
     183 * On success, the mofile will be placed in the $l10n global by
     184 * $domain and will be an gettext_reader object.
     185 *
     186 * @since 1.5.0
     187 * @uses $l10n Gets list of domain translated string (gettext_reader) objects
     188 * @uses CacheFileReader Reads the MO file
     189 * @uses gettext_reader Allows for retrieving translated strings
     190 *
     191 * @param string $domain Unique identifier for retrieving translated strings
     192 * @param string $mofile Path to the .mo file
     193 * @return null On failure returns null and also on success returns nothing.
     194 */
    63195function load_textdomain($domain, $mofile) {
    64196    global $l10n;
     
    75207}
    76208
     209/**
     210 * load_default_textdomain() - Loads default translated strings based on locale
     211 *
     212 * Loads the .mo file in LANGDIR constant path from WordPress root.
     213 * The translated (.mo) file is named based off of the locale.
     214 *
     215 * @since 1.5.0
     216 */
    77217function load_default_textdomain() {
    78218    $locale = get_locale();
     
    85225}
    86226
     227/**
     228 * load_plugin_textdomain() - Loads the plugin's translated strings
     229 *
     230 * If the path is not given then it will be the root of the plugin
     231 * directory. The .mo file should be named based on the domain with a
     232 * dash followed by a dash, and then the locale exactly.
     233 *
     234 * The plugin may place all of the .mo files in another folder and set
     235 * the $path based on the relative location from ABSPATH constant. The
     236 * plugin may use the constant PLUGINDIR and/or plugin_basename() to
     237 * get path of the plugin and then add the folder which holds the .mo
     238 * files.
     239 *
     240 * @since 1.5.0
     241 *
     242 * @param string $domain Unique identifier for retrieving translated strings
     243 * @param string $path Optional. Path of the folder where the .mo files reside.
     244 */
    87245function load_plugin_textdomain($domain, $path = false) {
    88246    $locale = get_locale();
     
    97255}
    98256
     257/**
     258 * load_theme_textdomain() - Includes theme's translated strings for the theme
     259 *
     260 * If the current locale exists as a .mo file in the theme's root directory, it
     261 * will be included in the translated strings by the $domain.
     262 *
     263 * The .mo files must be named based on the locale exactly.
     264 *
     265 * @since 1.5.0
     266 *
     267 * @param string $domain Unique identifier for retrieving translated strings
     268 */
    99269function load_theme_textdomain($domain) {
    100270    $locale = get_locale();
Note: See TracChangeset for help on using the changeset viewer.