Page History
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
Introduction
DSpace ships with a number of interface translations. This page provides information on areas where internationalization can be enabled 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.
XMLUI Internationalization
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.
DSpace XMLUI supplies an English only translation of the interface, which can be found in the XMLUI web application ([dspace]/webapps/xmlui/i18n/messages.xml), after you first build DSpace.
If you wish to add other translations to the system, or make customizations to the existing messages.xml file, you can place them in the following directory:
| Code Block |
|---|
[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 (and files of the same name will override any default files). By default this full directory path may not exist (if not, just create it) or may be empty. 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.
To set a language other than English as the default language for the repository's interface, you can simply set default.locale in dspace.cfg (this will work only if webui.supported.locales is uncommented and contains the value used in default.locale).
Again, note that you will need to rebuild DSpace for these changes to take effect in your installed XMLUI web application!
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
Latest language files
The XMLUI language files are updated and released separately from the DSpace core project. Visit the dspace-xmlui-lang project on Github.
JSPUI Internationalization
The Java Standard Tag Library v1.0 is used to specify messages in the JSPs like this:
OLD:
| Code Block |
|---|
<H1>Search Results</H1> |
NEW:
| Code Block |
|---|
<H1><fmt:message key="jsp.search.results.title"/></H1> |
This message can now be changed using the config/language-packs/Messages.properties file. (This must be done at build-time: Messages.properties is placed in the dspace.war Web application file.)
| Code Block |
|---|
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.
OLD:
| Code Block |
|---|
<P>Results <%= r.getFirst() %> to <%= r.getLast() %> of <%=r.getTotal() %></P> |
NEW:
| Code Block |
|---|
<fmt:message key="jsp.search.results.text"> <fmt:param><%= r.getFirst() %></fmt:param> <fmt:param><%= r.getLast() %></fmt:param> <fmt:param><%= r.getTotal() %></fmt:param> </fmt:message> |
(Note: JSTL 1.0 does not seem to allow JSP <%= %> expressions to be passed in as values of attribute in <fmt:param value=""/>)
The above would appear in the Messages_xx.properties file as:
| Code Block |
|---|
jsp.search.results.text = Results {0}-{1} of {2} |
Introducing number parameters that should be formatted according to the locale used makes no difference in the message key compared to string parameters:
| Code Block |
|---|
jsp.submit.show-uploaded-file.size-in-bytes = {0} bytes |
In the JSP using this key can be used in the way below:
| Code Block |
|---|
<fmt:message key="jsp.submit.show-uploaded-file.size-in-bytes"> <fmt:param><fmt:formatNumber><%= bitstream.getSize()%></fmt:formatNumber></fmt:param> </fmt:message> |
(Note: JSTL offers a way to include numbers in the message keys as jsp.foo.key = {0,number} bytes. Setting the parameter as <fmt:param value="${variable}" /> works when variable is a single variable name and doesn't work when trying to use method's return value instead: bitstream.getSize(). Passing the number as string (or using the <%= %> expression) does not work, either).
Multiple Messages.properties can be created for different languages. See ResourceBundle.getBundle. e.g. you can add German and Canadian French translations:
| Code Block |
|---|
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.)
Message Key Convention
When translating further pages, please follow the convention for naming message keys to avoid clashes.
For text in JSPs use the complete path + filename of the JSP followed by a single-word name for the message. e.g. for the title of jsp/mydspace/main.jsp use:
| Code Block |
|---|
jsp.mydspace.main.title |
Some common words (e.g. "Help") can be brought out into keys starting with jsp. for ease of translation (however, this is generally discouraged - two strings appearing in two places in the UI should have separate keys, even if the strings are identical), e.g.:
| Code Block |
|---|
jsp.admin = Administer |
Other common words/phrases are brought out into "general" parameters if they relate to a set (directory) of JSPs, e.g.
| Code Block |
|---|
jsp.tools.general.delete = Delete |
Phrases that relate strongly to a topic (eg. MyDSpace) but used in many JSPs outside the particular directory are more convenient to be cross-referenced. For example one could use the key below in jsp/submit/saved.jsp to provide a link back to the user's MyDSpace area:
(Cross-referencing of keys in general is not a good idea as it may make maintenance more difficult. But in some cases it has more advantages as the meaning is obvious.)
| Code Block |
|---|
jsp.mydspace.general.goto-mydspace = Go to My DSpace |
For text in servlet code, in custom JSP tags or wherever applicable use the fully qualified classname + a one-word name for the message. e.g.
| Code Block |
|---|
org.dspace.app.webui.jsptag.ItemListTag.title = Title |
Latest language files
The JSPUI language files are updated and released separately from the DSpace core project. Visit the dspace-api-lang project on Github.
Internationalization of Metadata
DSpace associates each metadata field value with a language code (though it may be left empty, e.g. for numeric values).
Overview
Content Tools