Old Release

This documentation relates to an old version of DSpace, version 5.x. Looking for another version? See all documentation.

Support for DSpace 5 ended on January 1, 2023.  See Support for DSpace 5 and 6 is ending in 2023

Introduction

DSpace ships with a number of interface translations. This page provides information on areas that can be localized by means of configuration or customization. By default, DSpace will look at the user's browser language. If it has a language file in the user's language, it will render the interface in that language. If not, it will default to English or another default that you have configured.

Common areas of localization

Enabling additional locales

Out of the box, DSpace only has English enabled as a supported locale. Additional locales and the default locale are managed through the following parameters in dspace.cfg:

dspace.cfg configuration parameters
webui.supported.locales
default.locale

You can change default.locale to a different one than English after adding it to webui.supported.locales.

Localization of email messages

All email templates used by DSpace can be found in

Path to the DSpace email templates
 [dspace]/config/emails

The contents of the emails can be edited and translated. 

Metadata localization

DSpace associates each metadata field value with a language code (though it may be left empty, e.g. for numeric values).

XMLUI specific localization

Message catalog

XMLUI supports multiple languages through the use of internationalization catalogues as defined by the Cocoon Internationalization Transformer. Each catalog contains the translation of all user-displayed strings into a particular language or variant. Each catalog is a single xml file whose name is based upon the language it is designated for, thus:

messages_language_country_variant.xml

messages_language_country.xml

messages_language.xml

messages.xml

The interface will automatically determine which file to select based upon the user's browser and system configuration. For example, if the user's browser is set to Australian English then first the system will check if messages_en_au.xml is available. If this translation is not available it will fall back to messages_en.xml, and finally if that is not available, messages.xml.

Where to find the message catalog

The latest English message catalog is part of the main DSpace distribution and can be found at:

Location of the XMLUI message catalog in the DSpace source tree
[dspace-source]/dspace-xmlui/src/main/webapp/i18n/messages.xml

The different translations for this message catalog are being managed separately from the DSpace core project, in order to release updates for these files more frequently than the DSpace software itself. Visit the dspace-xmlui-lang project on Github.

Where to edit

In some cases you may want to add additional keys to the message catalog or changing the particular wording of DSpace concepts. For example, you may want to change "Communities" into "Departments". These kind of changes may get automatically overwritten again when you upgrade to the newest version of DSpace. It is therefore advised to keep such changes isolated in the following location:

Recommended location for i18n customizations
[dspace-source]/dspace/modules/xmlui/src/main/webapp/i18n/

After rebuilding DSpace, any messages files placed in this directory will be automatically included in the XMLUI web application. Files of the same name will override any default files. By default, this full directory path may not exist or may be empty. If it does not exist, you can simply create it. You can place any number of translation catalogues in this directory. To add additional translations, just add another copy of the messages.xml file translated into the specific language and country variant you need. 

After building and deploying, DSpace will finally read the files from the following location:

Location where your i18n files are being deployed
[dspace]/webapps/xmlui/i18n/messages.xml

Again, note that you will need to rebuild DSpace for these changes to take effect in your installed XMLUI web application!

Do not customize your messages in the webapps directory

While it seems like a fast option to change your messages straight in the deployed dspace directory, these changes are very volatile. If you rebuild and redeploy DSpace, these changes will get lost.

For more information about the [dspace-source]/dspace/modules/ directory, and how it may be used to "overlay" (or customize) the default XMLUI interface, classes and files, please see: Advanced Customisation

Difference with JSPUI

In JSPUI, a wider range of files, including input-forms.xml and default.license can be localized by adding _COUNTRY at the end of the filename. This is currently not supported in XMLUI.

JSPUI specific localization

Message catalog

The Java Standard Tag Library v1.0 is used to specify messages in the JSPs like this:

<H1><fmt:message key="jsp.search.results.title"/></H1>

This message can be changed using the Messages.properties file. This must be done at build-time: Messages.properties is placed in the dspace Web application folder/archive.

jsp.search.results.title = Search Results

Phrases may have parameters to be passed in, to make the job of translating easier, reduce the number of 'keys' and to allow translators to make the translated text flow more appropriately for the target language. Here is an example of a phrase in which two parameters are passed in:

jsp.search.results.text = Results {0}-{1} of {2}

Multiple Messages.properties can be created for different languages. See ResourceBundle. e.g. you can add German and Canadian French translations:

Messages_de.properties
Messages_fr_CA.properties

The end user's browser settings determine which language is used by default. The user can change the language by clicking a link in the UI. These links are visible if more than one language is configured in DSpace. The English language file Messages.properties (or the default server locale) will be used as a fallback if there's no language bundle for the end user's preferred language. Note that the English file is not called Messages_en.properties. This is because it is always available as a fallback, regardless of server configuration.

Where to find the message catalog

The latest English message catalog is part of the main DSpace distribution and can be found at:

Location of the JSPUI message catalog in the DSpace source tree
[dspace-source]/dspace-api/src/main/resources/Messages.properties

The different translations for this message catalog are being managed separately from the DSpace core project, in order to release updates for these files more frequently than the DSpace software itself. Visit the dspace-api-lang project on Github.

Where to edit

In some cases you may want to add additional keys to the message catalog or changing the particular wording of DSpace concepts. For example, you may want to change "Communities" into "Departments". These kind of changes may get automatically overwritten again when you upgrade to the newest version of DSpace. It is therefore advised to keep such changes isolated in the following location:

Recommended location for i18n customizations
[dspace-source]/dspace/modules/jspui/src/main/resources/

After rebuilding DSpace, any messages files placed in this directory will be automatically included in the JSPUI web application. Files of the same name will override any default files. By default, this full directory path may not exist or may be empty. If it does not exist, you can simply create it. You can place any number of translation catalogues in this directory. To add additional translations, just add another copy of the Messages.properties file translated into the specific language and country variant you need. 

After building and deploying, DSpace will finally read the files from the dspace-api-5_x.jar file in your [tomcat]\webapps\jspui\WEB-INF\lib directory.

Again, note that you will need to rebuild DSpace for these changes to take effect in your installed JSPUI web application!

For more information about the [dspace-source]/dspace/modules/ directory, and how it may be used to "overlay" (or customize) the default JSPUI interface, classes and files, please see: Advanced Customisation

Localization of input-forms.xml and license.default

The display labels for input-forms.xml and the text in the default submission license (license.default) are currently not managed in the messages catalogs. To localize these files, you can create versions of these files in the same folders, appending _LANGUAGE or _LANGUAGE_COUNTRY at the end of the filename, before the extension. For example, input-forms_de.xml can be used to translate the submission form labels in German.

Community translations for input-forms.xml and email messages

Even though they are currently not managed on Github yet, some community translations are available for other files, such as emails and the input-forms.xml.

Click here to access an overview of community translations (DSpace wiki)

  • No labels

5 Comments

  1. Ivan Masár

    We should separate i18n and l10n. i18n doesn't belong to User Docs.

  2. Bram Luyten (Atmire)

    The two sections above are currently pretty much raw copies of what was already in the docs:

    Application Layer#Internationalization(JSPUIOnly)internationalization

    https://wiki.duraspace.org/display/DSDOC4x/XMLUI+Configuration+and+Customization#XMLUIConfigurationandCustomization-MultilingualSupport

    Just wanted to bring them together on one coherent page.

    But I agree that all i18n infrastructure details, enabling localization, should rather not be discussed here and removed.

    One thing that I'd like to have cleared up is the difference in localizing license and input forms files between XMLUI and JSPUI, as indicated here:

    Unable to locate Jira server for this macro. It may be due to Application Link configuration.

  3. Tiago Murakami

    Please, correct this patch:


    Recommended location for i18n customizations

     

    [dspace-source]/dspace/modules/jspui/src/main/resources/

    1. Bram Luyten (Atmire)

      corrected, thank you very much for this suggestion!

  4. Tim Donohue

    I like the direction this consolidated page is taking. However, I just wanted to note that we have duplicative and even possibly conflicting docs in other locations:

    It seems like we should interlink/consolidate these docs even more, or at least avoid duplication of this information in different sections of the documentation. Currently, depending on where you look in the docs, it's not entirely clear that 'webui.supported.locales' and 'webui.default.locale' settings work for BOTH XMLUI and JSPUI, as fixed in  Unable to locate Jira server for this macro. It may be due to Application Link configuration.

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.