Commit 04966aa0 authored by alexpott's avatar alexpott
Browse files

Issue #2578377 by YesCT, jhodgdon, Gábor Hojtsy, alexpott, herom, xjm: Make...

Issue #2578377 by YesCT, jhodgdon, Gábor Hojtsy, alexpott, herom, xjm: Make translatable docs consolidated and better for developers
parent ae32878a
...@@ -258,56 +258,39 @@ function drupal_get_path($type, $name) { ...@@ -258,56 +258,39 @@ function drupal_get_path($type, $name) {
/** /**
* Translates a string to the current language or to a given language. * Translates a string to the current language or to a given language.
* *
* The t() function serves two purposes. First, at run-time it translates * In order for strings to be localized, make them available in one of the ways
* user-visible text into the appropriate language. Second, various mechanisms * supported by the
* that figure out what text needs to be translated work off t() -- the text * @link https://www.drupal.org/node/322729 Localization API @endlink. When
* inside t() calls is added to the database of strings to be translated. * possible, use the \Drupal\Core\StringTranslation\StringTranslationTrait
* These strings are expected to be in English, so the first argument should * $this->t(). Otherwise create a new
* always be in English. To allow the site to be localized, it is important that * \Drupal\Core\StringTranslation\TranslatableMarkup object directly.
* all human-readable text that will be displayed on the site or sent to a user *
* is passed through the t() function, or a related function. See the * See \Drupal\Core\StringTranslation\TranslatableMarkup::__construct() for
* @link https://www.drupal.org/node/322729 Localization API @endlink pages for * important security information and usage guidelines.
* more information, including recommendations on how to break up or not *
* break up strings for translation. * @param string $string
* * A string containing the English text to translate.
* @section sec_translating_vars Translating Variables * @param array $args
* You should never use t() to translate variables, such as calling t($text) * (optional) An associative array of replacements to make after translation.
* unless the text that the variable holds has been passed through t() * Based on the first character of the key, the value is escaped and/or
* elsewhere (e.g., $text is one of several translated literal strings in an * themed. See
* array). It is especially important never to call t($user_text) where * \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
* $user_text is some text that a user entered - doing that can lead to * details.
* cross-site scripting and other security problems. However, you can use * @param array $options
* variable substitution in your string, to put variable text such as user * (optional) An associative array of additional options, with the following
* names or link URLs into translated text. Variable substitution looks like * elements:
* this: * - 'langcode' (defaults to the current language): A language code, to
* @code
* $text = t("@name's blog", array('@name' => $account->getDisplayName()));
* @endcode
* Basically, you can put variables like @name into your string, and t() will
* substitute their sanitized values at translation time. (See the
* Localization API pages referenced above and the documentation of
* \Drupal\Component\Utility\SafeMarkup::format() for details about how to
* define variables in your string.). Translators can then rearrange the string
* as necessary for the language (e.g., in Spanish, it might be "blog de
* @name").
*
* @param $string
* A string containing the English string to translate.
* @param $args
* An associative array of replacements to make after translation. Based
* on the first character of the key, the value is escaped and/or themed.
* See \Drupal\Component\Utility\SafeMarkup::format() for details.
* @param $options
* An associative array of additional options, with the following elements:
* - 'langcode' (defaults to the current language): The language code to
* translate to a language other than what is used to display the page. * translate to a language other than what is used to display the page.
* - 'context' (defaults to the empty context): The context the source string * - 'context' (defaults to the empty context): The context the source string
* belongs to. * belongs to.
* *
* @return \Drupal\Core\StringTranslation\TranslatableMarkup * @return \Drupal\Core\StringTranslation\TranslatableMarkup
* An object that, when cast to a string, will yield the translated string. * An object that, when cast to a string, returns the translated string.
*
* @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
* @see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
* @see \Drupal\Core\StringTranslation\TranslatableMarkup::__construct()
* *
* @see \Drupal\Component\Utility\SafeMarkup::format()
* @ingroup sanitization * @ingroup sanitization
*/ */
function t($string, array $args = array(), array $options = array()) { function t($string, array $args = array(), array $options = array()) {
......
...@@ -36,11 +36,39 @@ trait StringTranslationTrait { ...@@ -36,11 +36,39 @@ trait StringTranslationTrait {
/** /**
* Translates a string to the current language or to a given language. * Translates a string to the current language or to a given language.
* *
* See the t() documentation for details. * See \Drupal\Core\StringTranslation\TranslatableMarkup::__construct() for
* important security information and usage guidelines.
* *
* Never call $this->t($user_text) where $user_text is text that a user * In order for strings to be localized, make them available in one of the
* entered; doing so can lead to cross-site scripting and other security * ways supported by the
* problems. * @link https://www.drupal.org/node/322729 Localization API @endlink. When
* possible, use the \Drupal\Core\StringTranslation\StringTranslationTrait
* $this->t(). Otherwise create a new
* \Drupal\Core\StringTranslation\TranslatableMarkup object.
*
* @param string $string
* A string containing the English text to translate.
* @param array $args
* (optional) An associative array of replacements to make after
* translation. Based on the first character of the key, the value is
* escaped and/or themed. See
* \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
* details.
* @param array $options
* (optional) An associative array of additional options, with the following
* elements:
* - 'langcode' (defaults to the current language): A language code, to
* translate to a language other than what is used to display the page.
* - 'context' (defaults to the empty context): The context the source
* string belongs to.
*
* @return \Drupal\Core\StringTranslation\TranslatableMarkup
* An object that, when cast to a string, returns the translated string.
*
* @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
* @see \Drupal\Core\StringTranslation\TranslatableMarkup::__construct()
*
* @ingroup sanitization
*/ */
protected function t($string, array $args = array(), array $options = array()) { protected function t($string, array $args = array(), array $options = array()) {
return $this->getStringTranslation()->translate($string, $args, $options); return $this->getStringTranslation()->translate($string, $args, $options);
......
...@@ -13,13 +13,13 @@ ...@@ -13,13 +13,13 @@
/** /**
* Provides translatable markup class. * Provides translatable markup class.
* *
* This class delays translation until rendering. * This object, when cast to a string, will return the formatted, translated
* string. Avoid casting it to a string yourself, because it is preferable to
* let the rendering system do the cast as late as possible in the rendering
* process, so that this object itself can be put, untranslated, into render
* caches and thus the cache can be shared between different language contexts.
* *
* This is useful for using translation in very low level subsystems like entity * @see \Drupal\Component\Render\FormattableMarkup
* definition and stream wrappers.
*
* @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
* @see \Drupal\Core\StringTranslation\TranslationManager::translate()
* @see \Drupal\Core\StringTranslation\TranslationManager::translateString() * @see \Drupal\Core\StringTranslation\TranslationManager::translateString()
* @see \Drupal\Core\Annotation\Translation * @see \Drupal\Core\Annotation\Translation
*/ */
...@@ -58,17 +58,75 @@ class TranslatableMarkup extends FormattableMarkup { ...@@ -58,17 +58,75 @@ class TranslatableMarkup extends FormattableMarkup {
/** /**
* Constructs a new class instance. * Constructs a new class instance.
* *
* Parses values passed into this class through the t() function in Drupal and * When possible, use the
* handles an optional context for the string. * \Drupal\Core\StringTranslation\StringTranslationTrait $this->t(). Otherwise
* create a new \Drupal\Core\StringTranslation\TranslatableMarkup object
* directly.
*
* Calling the trait's t() method or instantiating a new TranslatableMarkup
* object serves two purposes:
* - At run-time it translates user-visible text into the appropriate
* language.
* - Static analyzers detect calls to t() and new TranslatableMarkup, and add
* the first argument (the string to be translated) to the database of
* strings that need translation. These strings are expected to be in
* English, so the first argument should always be in English.
* To allow the site to be localized, it is important that all human-readable
* text that will be displayed on the site or sent to a user is made available
* in one of the ways supported by the
* @link https://www.drupal.org/node/322729 Localization API @endlink.
* See the @link https://www.drupal.org/node/322729 Localization API @endlink
* pages for more information, including recommendations on how to break up or
* not break up strings for translation.
*
* @section sec_translating_vars Translating Variables
* $string should always be an English literal string.
*
* $string should never contain a variable, such as:
* @code
* new TranslatableMarkup($text)
* @endcode
* There are several reasons for this:
* - Using a variable for $string that is user input is a security risk.
* - Using a variable for $string that has even guaranteed safe text (for
* example, user interface text provided literally in code), will not be
* picked up by the localization static text processor. (The parameter could
* be a variable if the entire string in $text has been passed into t() or
* new TranslatableMarkup() elsewhere as the first argument, but that
* strategy is not recommended.)
*
* It is especially important never to call new TranslatableMarkup($user_text)
* or t($user_text) where $user_text is some text that a user entered -- doing
* that can lead to cross-site scripting and other security problems. However,
* you can use variable substitution in your string, to put variable text such
* as user names or link URLs into translated text. Variable substitution
* looks like this:
* @code
* new TranslatableMarkup("@name's blog", array('@name' => $account->getDisplayName()));
* @endcode
* Basically, you can put placeholders like @name into your string, and the
* method will substitute the sanitized values at translation time. (See the
* Localization API pages referenced above and the documentation of
* \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
* for details about how to safely and correctly define variables in your
* string.) Translators can then rearrange the string as necessary for the
* language (e.g., in Spanish, it might be "blog de @name").
* *
* @param string $string * @param string $string
* The string that is to be translated. * A string containing the English text to translate.
* @param array $arguments * @param array $arguments
* (optional) An array with placeholder replacements, keyed by placeholder. * (optional) An associative array of replacements to make after
* See \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for * translation. Based on the first character of the key, the value is
* additional information about placeholders. * escaped and/or themed. See
* \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
* details.
* @param array $options * @param array $options
* (optional) An array of additional options. * (optional) An associative array of additional options, with the following
* elements:
* - 'langcode' (defaults to the current language): A language code, to
* translate to a language other than what is used to display the page.
* - 'context' (defaults to the empty context): The context the source
* string belongs to.
* @param \Drupal\Core\StringTranslation\TranslationInterface $string_translation * @param \Drupal\Core\StringTranslation\TranslationInterface $string_translation
* (optional) The string translation service. * (optional) The string translation service.
* *
...@@ -76,6 +134,9 @@ class TranslatableMarkup extends FormattableMarkup { ...@@ -76,6 +134,9 @@ class TranslatableMarkup extends FormattableMarkup {
* Exception thrown when $string is not a string. * Exception thrown when $string is not a string.
* *
* @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat() * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
* @see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
*
* @ingroup sanitization
*/ */
public function __construct($string, array $arguments = array(), array $options = array(), TranslationInterface $string_translation = NULL) { public function __construct($string, array $arguments = array(), array $options = array(), TranslationInterface $string_translation = NULL) {
if (!is_string($string)) { if (!is_string($string)) {
......
...@@ -17,26 +17,36 @@ interface TranslationInterface { ...@@ -17,26 +17,36 @@ interface TranslationInterface {
/** /**
* Translates a string to the current language or to a given language. * Translates a string to the current language or to a given language.
* *
* Never call translate($user_text) where $user_text is text that a user * Never call this translate() method directly. In order for strings to be
* entered; doing so can lead to cross-site scripting and other security * localized, make them available in one of the ways supported by the
* problems. * @link https://www.drupal.org/node/322729 Localization API @endlink. When
* possible, use the \Drupal\Core\StringTranslation\StringTranslationTrait
* $this->t(). Otherwise create a new
* \Drupal\Core\StringTranslation\TranslatableMarkup object.
* *
* @param string $string * @param string $string
* A string containing the English string to translate. * A string containing the English text to translate.
* @param array $args * @param array $args
* An associative array of replacements to make after translation. Based * (optional) An associative array of replacements to make after
* on the first character of the key, the value is escaped and/or themed. * translation. Based on the first character of the key, the value is
* See \Drupal\Component\Utility\SafeMarkup::format() for details. * escaped and/or themed. See
* \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
* details.
* @param array $options * @param array $options
* An associative array of additional options, with the following elements: * (optional) An associative array of additional options, with the following
* - 'langcode': The language code to translate to a language other than * elements:
* what is used to display the page. * - 'langcode' (defaults to the current language): A language code, to
* - 'context': The context the source string belongs to. * translate to a language other than what is used to display the page.
* - 'context' (defaults to the empty context): The context the source
* string belongs to.
* *
* @return \Drupal\Core\StringTranslation\TranslatableMarkup * @return \Drupal\Core\StringTranslation\TranslatableMarkup
* An object that, when cast to a string, will yield the translated string. * An object that, when cast to a string, returns the translated string.
* *
* @see \Drupal\Component\Utility\SafeMarkup::format() * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
* @see \Drupal\Core\StringTranslation\TranslatableMarkup::__construct()
*
* @ingroup sanitization
*/ */
public function translate($string, array $args = array(), array $options = array()); public function translate($string, array $args = array(), array $options = array());
......
...@@ -123,7 +123,7 @@ public function translateString(TranslatableMarkup $translated_string) { ...@@ -123,7 +123,7 @@ public function translateString(TranslatableMarkup $translated_string) {
* Translates a string to the current language or to a given language. * Translates a string to the current language or to a given language.
* *
* @param string $string * @param string $string
* A string containing the English string to translate. * A string containing the English text to translate.
* @param array $options * @param array $options
* An associative array of additional options, with the following elements: * An associative array of additional options, with the following elements:
* - 'langcode': The language code to translate to a language other than * - 'langcode': The language code to translate to a language other than
......
...@@ -362,7 +362,7 @@ if (window.jQuery) { ...@@ -362,7 +362,7 @@ if (window.jQuery) {
* See the documentation of the server-side t() function for further details. * See the documentation of the server-side t() function for further details.
* *
* @param {string} str * @param {string} str
* A string containing the English string to translate. * A string containing the English text to translate.
* @param {Object.<string, string>} [args] * @param {Object.<string, string>} [args]
* An object of replacements pairs to make after translation. Incidences * An object of replacements pairs to make after translation. Incidences
* of any key in this array are replaced with the corresponding value. * of any key in this array are replaced with the corresponding value.
......
...@@ -66,7 +66,7 @@ public function testFormatPlural($count, $singular, $plural, array $args = array ...@@ -66,7 +66,7 @@ public function testFormatPlural($count, $singular, $plural, array $args = array
* Tests translation using placeholders. * Tests translation using placeholders.
* *
* @param string $string * @param string $string
* A string containing the English string to translate. * A string containing the English text to translate.
* @param array $args * @param array $args
* An associative array of replacements to make after translation. * An associative array of replacements to make after translation.
* @param string $expected_string * @param string $expected_string
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment