Add internationalization (i18n) to document types - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 10. There's an updated version available that covers our most recent release.

26-11-2015

Add internationalization (i18n) to document types

Internationalization of document type names

The Hippo CMS 10 user may login with different languages. You can add translations for every document type name so the users can see document type names in their own language. To do so, go to the Hippo console and select the document type(s) whose name should be translated, e.g. /hippo:namespaces/demo/newsitem

  • Add a mixin type hippo:translated to the document type

  • Add a node hippo:translation of primary type hippo:translation

    • Add a property hippo:language of type String and fill in the language abbreviation (" nl" or " en").

    • Add a property hippo:message of type String and fill in the translated document type

  • If you are editing from the console, don't forget to click the button "Write changes to repository"

In XML it looks like:

<sv:node sv:name="newsitem" xmlns:sv="http://www.jcp.org/jcr/sv/1.0">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hippo:templatetype</sv:value>
  </sv:property>
  <sv:property sv:name="jcr:mixinTypes" sv:type="Name">
    <sv:value>mix:referenceable</sv:value>
    <sv:value>hippo:translated</sv:value>
  </sv:property>
  <sv:node sv:name="hippo:translation">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>hippo:translation</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:language" sv:type="String">
      <sv:value>nl</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:message" sv:type="String">
      <sv:value>Nieuws</sv:value>
    </sv:property>
  </sv:node>
  <sv:node sv:name="hippo:translation">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>hippo:translation</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:language" sv:type="String">
      <sv:value>en</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:message" sv:type="String">
      <sv:value>News</sv:value>
    </sv:property>
  </sv:node>
  <!-- the rest of the document type definition -->
</sv:node>

Internationalization of field captions

Above works for the names of the document types, but what about the field captions? They can be internationalized by providing a translator service to subclasses of RenderPlugin. These plugin classes are configured below editor:templates nodes in the template. The steps are as follows:

  • On the node editor:templates/_default_, add a String property translator.id with value ${cluster.id}.translator
  • Below node editor:templates/_default_, add a node with name translator and primary type frontend:plugin.
  • Add mixin type: hippostd:translated
  • Add the String property:  plugin.class with value org.hippoecm.frontend.i18n.ConfigTraversingPlugin
  • Below the new translator node, add a node with name hippostd:translations of primary type hippostd:translations
  • Below hippostd:translations node, add nodes of type frontend:pluginconfig with the same name as the field that should be translated. For example, the field "title" should correspond to a node with name "title". In the case of translated document field hints, the convention is to name the node "title.hint" to refer to the hint for the title field (see next section).
  • Below the nodes of type frontend:pluginconfig, add multiple hippo:translation nodes like we did for the document type translations, each as the localized field name.
  • In the CMS, the localized field name will be used in favour of the caption property. If the localized field name is not found, the caption property is displayed.

Internationalization of field hints

Document field hints can be internationalized/translated in the very same way as field captions are. Make sure that the value of the field's hint property matches the node name of the corresponding translation nodes. As a best practice, use a value of "<fieldname>.hint".

Example

The XML notation for document field translation looks like:

<sv:node sv:name="editor:templates">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>editor:templateset</sv:value>
  </sv:property>
  <sv:node sv:name="_default_">
    <!-- skipped properties -->

    <sv:property sv:name="translator.id" sv:type="String">
      <sv:value>${cluster.id}.translator</sv:value>
    </sv:property>
    <!-- the translator -->
    <sv:node sv:name="translator">
      <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>frontend:plugin</sv:value>
      </sv:property>
      <sv:property sv:name="jcr:mixinTypes" sv:type="Name">
        <sv:value>hippostd:translated</sv:value>
      </sv:property>
      <sv:property sv:name="plugin.class" sv:type="String">
        <sv:value>org.hippoecm.frontend.i18n.ConfigTraversingPlugin</sv:value>
      </sv:property>
      <sv:node sv:name="hippostd:translations">
        <sv:property sv:name="jcr:primaryType" sv:type="Name">
          <sv:value>hippostd:translations</sv:value>
        </sv:property>
        <sv:node sv:name="title">
          <sv:property sv:name="jcr:primaryType" sv:type="Name">
            <sv:value>frontend:pluginconfig</sv:value>
          </sv:property>
          <sv:property sv:name="jcr:mixinTypes" sv:type="Name">
            <sv:value>hippo:translated</sv:value>
          </sv:property>
          <sv:node sv:name="hippo:translation">
            <sv:property sv:name="jcr:primaryType" sv:type="Name">
              <sv:value>hippo:translation</sv:value>
            </sv:property>
            <sv:property sv:name="hippo:language" sv:type="String">
              <sv:value>nl</sv:value>
            </sv:property>
            <sv:property sv:name="hippo:message" sv:type="String">
              <sv:value>Titel</sv:value>
            </sv:property>
          </sv:node>
          <sv:node sv:name="hippo:translation">
            <sv:property sv:name="jcr:primaryType" sv:type="Name">
              <sv:value>hippo:translation</sv:value>
            </sv:property>
            <sv:property sv:name="hippo:language" sv:type="String">
              <sv:value>en</sv:value>
            </sv:property>
            <sv:property sv:name="hippo:message" sv:type="String">
              <sv:value>Title</sv:value>
            </sv:property>
          </sv:node>
        </sv:node>
        <sv:node sv:name="title.hint">
          <sv:property sv:name="jcr:primaryType" sv:type="Name">
            <sv:value>frontend:pluginconfig</sv:value>
          </sv:property>
          <sv:property sv:name="jcr:mixinTypes" sv:type="Name">
            <sv:value>hippo:translated</sv:value>
          </sv:property>
          <!-- see above, add translations with language and message -->
          <sv:node sv:name="hippo:translation">

          </sv:node>
        </sv:node>
      </sv:node>
    </sv:node>

    <!-- skipped ListViewPlugin node etc. -->

    <sv:node sv:name="title">
      <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>frontend:plugin</sv:value>
      </sv:property>
      <sv:property sv:name="field" sv:type="String">
        <sv:value>title</sv:value>
      </sv:property>
      <sv:property sv:name="hint" sv:type="String">
        <sv:value>title.hint</sv:value>
      </sv:property>
      <sv:property sv:name="plugin.class" sv:type="String">
        <sv:value>org.hippoecm.frontend.editor.plugins.field.NodeFieldPlugin </sv:value>
      </sv:property>
      <sv:property sv:name="wicket.id" sv:type="String">
        <sv:value>${cluster.id}.field</sv:value>
      </sv:property>
      <sv:node sv:name="cluster.options">
        <sv:property sv:name="jcr:primaryType" sv:type="Name">
          <sv:value>frontend:pluginconfig</sv:value>
        </sv:property>
      </sv:node>
    </sv:node>
  </sv:node>
</sv:node>

Above solution concerns one embedded translation service per document type. If you want to use same translations over multiple types, a global translator may be added to the main CMS configuration ( /hippo:configuration/hippo:frontend/cms/cms-static) or the services node when available ( /hippo:configuration/hippo:frontend/cms/cms-services)

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?