Mercury Documentation

Expand Mercury search in OpenCms

July 30, 2025 Alkacon Software
Unlock multilingual power in OpenCms! Learn how to enable Mercury's search for new locales like Spanish with simple tweaks to your configuration files.
Frau schaut durch eine Lupe Frau schaut durch eine Lupe
Frau schaut durch eine Lupe

In the previous Dev Blog, we covered how to set up a new website using the Mercury template. In this post, we’ll walk through the steps required to configure the Mercury search functionality for locales beyond the default English and German locales provided by OpenCms.

By adjusting OpenCms and Solr settings, you can enable multilingual search capabilities for languages like Spanish, enhancing the user experience on your internationalized website.

To follow along, you’ll need access to the system configuration files of your OpenCms installation. While some familiarity with Solr is helpful, it is not strictly required.

By default, OpenCms supports English (en) and German (de) as system locales. To use additional languages—for example, Spanish (es)—you must first register the new locale in the core configuration.

Modify opencms-system.xml

  • Locate the configuration file at: /WEB-INF/config/opencms-system.xml
  • Search for the <internationalization> section near the top of the file.
  • Add the desired locale (es) to both <localesconfigured> and <localesdefault> blocks:

[...]
<internationalization>
    <localehandler class="org.opencms.i18n.CmsDefaultLocaleHandler"/>
    <localesconfigured>
       <locale>en</locale>
       <locale>de</locale>
       <locale>es</locale>
    </localesconfigured>
    <localesdefault>
      <locale>en</locale>
      <locale>de</locale>
      <locale>es</locale>
    </localesdefault>
    <timezone>GMT+01:00</timezone>
</internationalization>
[...]
  • Restart OpenCms to apply the new locale settings.

For more general guidance on multilingual setup in OpenCms, refer to the OpenCms documentation on localization.

OpenCms Documentation: Building a multilingual website

The Mercury search is configured to support only 'en' and 'de' out-of-the-box. To enable support for additional locales like 'es', some adjustments to the Solr configuration are necessary.

Update schema.xml

  • Open the following file: /WEB-INF/solr/configsets/default/conf/schema.xml
  • Add the following for Spanish:

[...]
<!-- es Spell-checking / Suggestion field, using maxShingleSize=2 -->
<fieldType name="spell_es" class="solr.TextField" positionIncrementGap="100">
    <analyzer>
        <tokenizer class="solr.StandardTokenizerFactory"/>
        <filter class="solr.LowerCaseFilterFactory"/>
        <filter class="solr.StopFilterFactory" ignoreCase="true" words="lang/stopwords_es.txt"/>
        <filter class="solr.ShingleFilterFactory" maxShingleSize="2" outputUnigrams="true"/>
        <filter class="solr.RemoveDuplicatesTokenFilterFactory"/>
    </analyzer>
</fieldType>
[...]
  • Add the corresponding field definition:

[...]
<field name="es_spell" type="spell_es" indexed="true" stored="false" multiValued="true"/>
[...]

Note: For supported locales like el, es, fi, fr, hu, and it, only the spellcheck fields need to be added. For others (e.g., pl), additional field types for this locale must be defined:


[...]
<!-- Polish -->
<fieldType name="text_pl" class="solr.TextField" positionIncrementGap="100">
    <analyzer>
        <tokenizer class="solr.StandardTokenizerFactory"/>
        <filter class="solr.LowerCaseFilterFactory"/>
        <filter class="solr.StopFilterFactory" ignoreCase="true" words="lang/stopwords_pl.txt" format="snowball"/>
        <filter class="solr.StempelPolishStemFilterFactory"/>
    </analyzer>
</fieldType>

[…]

<field name="text_pl" type="text_pl" indexed="true" stored="false" multiValued="true"/>

[…]

<dynamicField name="*_pl" type="text_pl" indexed="true" stored="true" multiValued="true"/>

[…]

<copyField source="*_pl" dest="text_pl"/>

[...]

Make sure the corresponding stopwords_*.txt file exists in: /WEB-INF/solr/configsets/default/conf/lang/

With those changes, the modification of the schema.xml is completed.

 

Update solrconfig.xml

  • Open: /WEB-INF/solr/configsets/default/conf/solrconfig.xml
  • Add a new <lst> block for your new locale (e.g. 'es')  under the spellcheck component:

[...]
<lst name="spellchecker">
    <str name="name">es</str>
    <str name="field">es_spell</str>
    <str name="classname">solr.DirectSolrSpellChecker</str>
    <str name="distanceMeasure">internal</str>
    <float name="accuracy">0.5</float>
    <int name="maxEdits">2</int>
    <int name="minPrefix">1</int>
    <int name="maxInspections">5</int>
    <int name="minQueryLength">5</int>
    <float name="maxQueryFrequency">0.001</float>
    <float name="thresholdTokenFrequency">.001</float>
</lst>
[...]

Once all changes are made, restart OpenCms to apply the new Solr and locale configurations. The Mercury search function now fully supports the newly added locale.