ibexa

Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.

d18n

Summary

Marks a string for translation. Valid from 4.3

Usage

input|d18n( context [, comment [, arguments ] ] )

Parameters

NameTypeDescriptionRequired
context string The context to which the string belongs. Yes.
comment string A comment describing the text. No.
arguments hash An associative array of arguments in the input parameter. No.

Returns

A string containing a translated version of the input parameter.

Description

This adds a new template operator "d18n", it's an alias for i18n() operator and behaves just like it, only difference is that ezlupdate (qt scripts that generates translation files) will ignore it so it can be used for dynamic strings (variables). This operator makes it possible to translate static strings that are defined in various templates. It is typically useful to ensure that the HTML interface is available in several languages in a multi-language scenario.

The operator takes one required parameter "context", and two optional parameters: "comment" and "arguments". The "context" parameter should be used to specify a group to which the input parameter should be related. This is typically useful when there are a lot of strings that need to be structured/grouped. The "comment" parameter makes it possible to add additional comment which can help the person responsible for doing the actual translation. A comment could for example be "Button label" - revealing what that mysterious string actually is. The "arguments" parameter makes it possible to mix dynamic text into the translations. Please refer to "Example 2" for a demonstration of this feature.

Note: This template operator was added from version 4.3 onwards.

Examples

Example 1

{"Are you sure you want to remove these items?"|d18n('design/standard/node')}

Outputs "Are you sure you want to remove these items?" translated to the current language. The translation is taken from the context block named "design/standard/node" located in the appropriate translation file.

For example, let's say that the "translation.ts" file located in the "share/translations/ita-IT/" directory of your eZ Publish installation contains the following lines:

<context>
<name>design/standard/node</name>
 ...
<message>
<source>Are you sure you want to remove these items?</source>
<translation>Sei sicuro di voler rimuovere questi elementi?</translation>
</message>
 ...
</context>

If your current system locale is "ita-IT" (as specified in the " Locale" setting located in the "[RegionalSettings]" section of the "settings/site.ini" configuration file or its override) then the following output is produced: "Sei sicuro di voler rimuovere questi elementi?"

Example 2

{def $number=5}
{"Please enter %number characters."|d18n('design/standard/node', '', hash( '%number', $number ) )}

Outputs "Please enter 5 characters.", the %number will be dynamically replaced by the variable.

Geir Arne Waaler (17/12/2010 2:32 pm)

Geir Arne Waaler (20/12/2010 3:31 pm)


Comments

  • encoding and html entities

    Using special characters, accents and so on, generally works fine (as long as you properly set the character encoding of the files, of course), but if you would like to use html entities instead, you should "double code" the translation.ts file :

    "&eacute;" should become "&amp;eacute;"
    "&amp;" should become "&amp;amp;"
    "&gt;" should become "&amp;gt;"
    etc...

    For example : if the string you would like to convert looks like

    let's do it

    and the source code of your template is

    {"let&apos;s do it"|d18n()}

    then the translation.ts should contain the following message :

    <message>
    <source>let&amp;apos;s do it</source>
    <translation>translated let&amp;apos;s do it</translation>
    </message>

    It seems that ez Publish parses the html entities in the translation.ts file first before it actually compares the messages. I'm not sure why it actually performs that way, but it sure is something you should know about since the whole translation file can get rejected if it encounters quotes ( ' or " ), greater than ( > ) or smaller than ( < ) since the parsed file is no longer a valid XML file...
    • Re: encoding and html entities

      You can also use CDATA if needed to "escape" non-valid xml characters:

      <message>
      <source>Drink a coffee</source>
      <translation><![CDATA[Boire un caf&eacute;]]></translation>
      </message>