diff --git a/docs/en/changelogs/3.0.0.md b/docs/en/changelogs/3.0.0.md index 2f82f218ac5..21809a68de2 100644 --- a/docs/en/changelogs/3.0.0.md +++ b/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. diff --git a/docs/en/topics/i18n.md b/docs/en/topics/i18n.md index e9c287b1dca..6619004fa3e 100644 --- a/docs/en/topics/i18n.md +++ b/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 - ) - -