Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

MINOR: updating the documentation

  • Loading branch information...
commit 7710cf59c787cc1efbcdb48c22115f81200acc18 1 parent 90ae0ed
@candidasa candidasa authored
Showing with 34 additions and 31 deletions.
  1. +11 −1 docs/en/changelogs/3.0.0.md
  2. +21 −29 docs/en/topics/i18n.md
  3. +2 −1  i18n/i18n.php
View
12 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.
View
50 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
@drzax
drzax added a note

As far as I can tell this section of the documentation in the 3.0 branch refers to functionality that never got implemented in 3.0 (and doesn't look to be implemented in 3.1 either). I see nothing in https://github.com/silverstripe/sapphire/blob/3.0/javascript/i18n.js which would do injection of named replacement, though the sprintf function still exists.

Is that correct or am I missing something?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
:::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?"
View
3  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 = "") {

5 comments on commit 7710cf5

@chillu
Owner

True, reverted in 64888c0 - I think @candidasa misunderstood the feature, it was only implemented for PHP

@drzax

Is anyone working on this? The javascript _t() implementation is pretty impoverished at the moment. I know any change will require updating a lot of core code, but it certainly seems like something that should be looked at. Replacement ordering is very important for translation.

I'll be implementing a replacement for ss.i18n._t() for a current project which I'll be happy to share, but is unlikely to work as a drop-in replacement.

@chillu
Owner

Nobody working on it, happy for you to have a crack. Just be aware that it shouldn't have much in terms of dependencies (definitely no entwine), since its designed as a standalone library. jQuery might be fine though. Named param support would be grand!

@drzax

I wouldn't expect to need jQuery or entwine anyway since it shouldn't need to hit the DOM at any point. A more wholesale re-implementation might look at using require.js (or that concept) to load the language files rather than the current tight coupling with the PHP Requirements class (which incidentally, also leaves quite a bit to be desired, IMO).

But that's beyond what I can achieve in the next few days - which is the time frame I'm working with. For now I'll just be looking at a simple replacement for _t()

@chillu
Owner
Please sign in to comment.
Something went wrong with that request. Please try again.