I was recently asked how one can manage vocabulary localization in-app instead of using i18n files deployed as part of the configuration. To my surprise it has actually been possible since the version 6.0. This feature went so unnoticed that almost nobody knows about it (at least I avoided the shame of being the only one at Nuxeo not knowing about it! ).

Vocabularies are lookup tables that you can use with suggestion widgets in the Nuxeo Platform.

Suggestion Widget
Suggestion Widget

Each entry typically consists of a key and a label. But of course if you have users who speak different languages, you may want the labels to be localized for each language. Since it’s definitely not cool having to update the configuration just to add/change an entry and its translations, the Nuxeo Platform lets you do that directly in-app and also provides an API Endpoint for it. But first you need to configure the vocabulary.

In the end a vocabulary is just another name for the more generic abstraction called Directory. The first thing we need in order to configure a new directory is a schema which contains one property for each language we want to support. Here we’ll use English, French, Spanish and German.

<?xml version="1.0"?>
    <xs:element name="id" type="xs:string"/>
    <xs:element name="parent" type="xs:string"/>
    <xs:element name="label_en" type="xs:string"/>
    <xs:element name="label_fr" type="xs:string"/>
    <xs:element name="label_es" type="xs:string"/>
    <xs:element name="label_de" type="xs:string"/>
    <xs:element name="obsolete" type="xs:integer" default="0"/>

Note that the same schema can be reused for multiple vocabularies. Next we can declare our directory with the corresponding extension point.

<component name="org.nuxeo.samples.vocabularies.l10n.directory">
    <extension point="directories" target="org.nuxeo.ecm.directory.sql.SQLDirectoryFactory">
        <directory name="customl10ncoverage">

Just with that, we can already use the Directory API Endpoint to get, add, update, or delete entries in our new customl10ncoverage directory. Was fairly easy right?

Nuxeo API playground
Nuxeo API playground

Moreover the vocabulary is also available for use with the suggestion widget in the UI. We can see below that the labels are localized when we change the user locale.

Suggestion widget with localized labels
Suggestion widget with localized labels (English)

Suggestion widget with localized labels
Suggestion widget with localized labels (German)

The configuration of the widget with Nuxeo Studio couldn’t be easier. We only need to use the suggestOneDirectory widget with a string property, set the vocabulary name (with a custom property) and make sure that we set the localize and Activate database localization properties to true.

Widget Editor in Nuxeo Studio
Widget Editor in Nuxeo Studio

Let’s go further and make the vocabulary manageable from the Admin Center. In order to do that we need to define a layout for and register it. I won’t get into the details for this part, but if you want to know more, the layout XML configuration is available here.

Vocabulary Editor in the Admin Center
Vocabulary Editor in the Admin Center

Finally, nothing is set in stone and you can absolutely add new languages later just by updating the schema and the Admin Center layout. The full source of this example is in our github repository.