MINOR: updating the documentation

docs/en/changelogs/3.0.0.md

@@ -365,7 +365,17 @@ placeholder and the `PageComment` class. See the ['comments' module](https://git
 
 The setting determines difference homepages at arbitrary locations in the page tree,
 and was rarely used in practice - so we moved it to a "[homepagefordomain](https://github.com/silverstripe-labs/silverstripe-homepagefordomain)" module.
-
+
+### New syntax for translatable _t functions ###
+
+You can now call the _t() function in both templates and code with a namespace and string to translate, as well as a
+comment and injection array. Note that the proxity arguement to _t is no longer supported.
+
+The new syntax supports injecting variables into the translation. For example:
+
+	:::php
+    _t('i18nTestModule.INJECTIONS2', "Hello {name} {greeting}", array("name"=>"Paul", "greeting"=>"good you are here"));
+
 ### Default translation source in YML instead of PHP $lang array, using Zend_Translate ###
 
 This allows for a more flexible handling of translation sources in various formats.

docs/en/topics/i18n.md

@@ -139,20 +139,18 @@ The `_t()` function is the main gateway to localized text, and takes four parame
 
  * **$entity:** Unique identifier, composed by a namespace and an entity name, with a dot separating them. Both are arbitrary names, although by convention we use the name of the containing class or template. Use this identifier to reference the same translation elsewhere in your code. 
  * **$string:** (optional) The original language string to be translated. Only needs to be declared once, and gets picked up the [text collector](#collecting-text).
- * **$string:** (optional) Natural language (particularly short phrases and individual words)
+ * **$string:** (optional) Natural language comment (particularly short phrases and individual words)
 are very context dependent. This parameter allows the developer to convey this information
-to the translator. Can also be used to explain `sprintf()` placeholders.
+to the translator.
+ * **$array::** (optional) An array of injecting variables into the second parameter
 
 	:::php
 	//Example 4: Using context to hint information about a parameter
-	sprintf(
-		_t('CMSMain.RESTORED', 
-			"Restored '%s' successfully", 
-			'Param %s is a title'
-		),
-		$title
-	)
-
+	_t('CMSMain.RESTORED',
+		"Restored {value} successfully",
+		'This is a message when restoring a broken part of the CMS',
+		array('value' => $itemRestored)
+	);
 
 ### Usage
 
@@ -182,25 +180,21 @@ Therefore, the following would be a valid use in templates:
 
 Using SS templating variables in the translatable string (e.g. $Author, $Date..) is not currently supported.
 
-### sprintf()-support
+### Injection-support
 
-Sprintf enables us to dynamically replace parts of a translated string, e.g. by a username or a page-title.
+Variable injection in _t allows us to dynamically replace parts of a translated string, e.g. by a username or a page-title.
 
 	:::php
 	// in PHP-file
-	sprintf(
-	     _t('CMSMain.RESTORED',"Restored '%s' successfully"),
-	     $title
-	)
-
-<div class="warning" markdown='1'>
-**Caution**: In templates (*.ss)-files you can only use ONE argument for your sprintf-support, and can't use spaces
-between parameters.
-</div>
+	_t(
+		'CMSMain.RESTORED',
+		"Restored {title} successfully"),
+		array('title' => $title)
+	);
 
 	:::php
-	// in SS-template ($title must be available in the current template-scope)
-	<% sprintf(_t('CMSMain.RESTORED',"Restored '%s' successfully"),$title) %>
+	// in SS-template ($Name must be available in the current template-scope)
+	<%t MYPROJECT.INJECTIONS "Hello {name} {greeting}" name="$Name" greeting="good to see you" %>
 
 
 ## Collecting text
@@ -339,14 +333,12 @@ Example Translation Table (mymodule/javascript/lang/de_DE.js)
 	alert(ss.i18n._t('MYMODULE.MYENTITY'));
 
 
-### Advanced Usage with sprintf()
+### Advanced Usage with injection
 
 	:::js
-	// MYMODULE.MYENTITY contains "Really delete %s articles by %s authors?"
-	alert(ss.i18n.sprintf(
-	  ss.i18n._t('MYMODULE.MYENTITY'),
-	  42,
-	  'Douglas Adams'
+	// MYMODULE.MYENTITY contains "Really delete {answer} articles by {author} authors?"
+	alert(ss.i18n._t('MYMODULE.MYENTITY'),
+		array('answer' => 42, 'author' => 'Douglas Adams')
 	));
 	// Displays: "Really delete 42 articles by Douglas Adams?"
 

i18n/i18n.php

@@ -1457,7 +1457,8 @@ public static function get_time_format() {
 	 * @param string $string The original string itself. In a usual call this is a mandatory parameter, but if you are reusing a string which
 	 *				 has already been "declared" (using another call to this function, with the same class and entity), you can omit it.
 	 * @param string $context (optional) If the string can be difficult to translate by any reason, you can help translators with some more info using this param
-	 * @param string injectionArray (optional) array of key value pairs that are used to replace corresponding expressions in {curly brackets} in the $string
+	 * @param string injectionArray (optional) array of key value pairs that are used to replace corresponding expressions in {curly brackets} in the $string.
+	 *               The injection array can also be used as the their argument to the _t() function
 	 * @return string The translated string, according to the currently set locale {@link i18n::set_locale()}
 	 */
 	static function _t($entity, $string = "", $context = "", $injection = "") {