Using (global) tranlations in Dynamicweb

Dynamicweb CMS offeres a simple translation system, which uses keys combined with language settings on a website to give various translation for static texts. The system can use global and local keys, where the local translations relate to a specific module, the global can be shared globally.

I will focus on the Global tranlations here.

Translations.xml – the container of your translations

When you need to make a phrase in various languages you should use the Tranlations.xml file found under “/files/templates/”. The structure is like this:

<?xml version="1.0" encoding="utf-8"?>
<translations>
  <key name="order">
    <translation culture="it-IT"><![CDATA[Ordina]]></translation>
    <translation culture="en-GB"><![CDATA[Place order]]></translation>
    <translation culture="da-DK"><![CDATA[Bestil]]></translation>
  </key>
</translations>

As you can see it is basic XML structure. The file root is “translations”, and as child node you add your “key”, one for each phrase you need to translate. For each language (translation) you should add a “translation” element under the “key” element. In the above example it is the phrase “order” which has three translations. It is defined in italian, english and danish. I consider it good practise to wrap the translation value into CDATA, that way you are more sure that your XML is valid, even with special chars. You can find the value of the “culture” attribute on the settings for the website you define in Dynamicweb CMS.

An example of use

Lets say that we have to use the phrase “Minimum Order:” in some websites which different languages.

We start by adding a key to the “templates/tranlations.xml”:

  <key name="minimumorder">
    <translation culture="it-IT"><![CDATA[ Ordine Minimo]]></translation>
    <translation culture="en-GB"><![CDATA[ Minimum Order]]></translation>
    <translation culture="da-DK"><![CDATA[ Minimum bestilling]]></translation>
  </key>

Now the phrase “minimumorder” will have tranlations in the three languages in italian, english and danish.

HTML templates

With the phrase defined you should use it inside your template. There is a tag defined for the task:

<!--@Translate(minimumorder, " Minimum Order", global)-->

Where ever you insert this tag into your templates it will be replaced with the pharse in the language for the website where the template is used. So for Danish you would get ” Minimum bestilling” where the tag is placed.

XSLT templates

If you template is in XSLT it is not so straightforward how it works. You need to add these lines to your XSLT: In the top we fetch the tranlations.xml document into a variable, but we also need to defined some “helper” variables:

<xsl:variable name="Host" select="/Template/GlobalTags/Global.Request.Host" />

That will contain the name of the host, which we will need below to get the tranlationfile:

<xsl:variable name="translationfile" select="document(concat('http://',$Host,'/Files/Templates/Translations.xml'))" />

now the variable $translationfile will contain the XML containing the translations.
We also need to know which languange is the current language, so lets define a variable called “currentlanguage”:

<xsl:variable name="currentlanguage" select="/Template/GlobalTags/Global.Area.LongLang" />

Those three lines should be placed above the first

<xsl:template match="/">

To find a translation we defined at template:

  <xsl:template name="translate">
    <xsl:param name="translationkey" />
    <xsl:param name="defaulttranslation" />
    <xsl:choose>
      <xsl:when test="$translationfile/translations/key[@name=$translationkey]">
        <xsl:value-of select="$translationfile/translations/key[@name=$translationkey]/translation[@culture=string($currentlanguage)]" />
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="$defaulttranslation" />
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

It takes two parameters, and not three as this implementation only handles global translations. The parameters are “translationkey” and “defaulttranslation”, guess you can figure out what to put into them. We are now ready to use translations in XSLT… You can find link to boilerplate at the bottom of this post.

Using the translate template in XSLT

In XSLT you should use these lines to translate something found in Translations.xml:

<xsl:call-template name="translate">
  <xsl:with-param name="translationkey" select="'minimumorder'" />
  <xsl:with-param name="defaulttranslation" select="'Minimum Order:'" />
</xsl:call-template>

In the above call to “translate” we will look for a key called “minimumorder” in the current language. If the key is not defined for the current language, or not at all, “Minimum Order:” will be inserted.

So there you go! You can now start playing with the tranlations system of Dynamicweb CMS.

Links

• dynamicwebGlobalTranslationsInXSLT.xslt – translation boilerplate
• Snippet for Visual Studio to add HTML translate tag
• Snippet for Visual Studio which creates a translation key for Dynamicweb Translation.xml