Dev Blog:How to Configure the Mercury Search Function for Additional Locales

Date:
July 30, 2025
Expand Mercury search in OpenCms with new locales like Spanish. This guide shows how to adjust configuration files in OpenCms and Solr to support multilingual search functionality.
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.

Add New Locales to OpenCms

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

Extend Mercury Search for Additional Locales

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>
[...]

Restart OpenCms

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.