Language localisation

WARNING: These instructions apply for 2017.04 and newer releases.

Localising your installation

In localising clarin-dspace for a particular language, the following steps should be taken:

1. Determine the two-letter locale language code (e.g., "de" for German).
2. Create your locale versions of the XML messages file, JS messages file, and license, copied from the English versions:

• XML: dspace-xmlui/src/main/webapp/i18n/messages.xml -> dspace/modules/xmlui/src/main/webapp/i18n/messages_de.xml
• JS: dspace-xmlui/src/main/webapp/themes/UFAL/lib/js/messages/messages.js -> dspace-xmlui/src/main/webapp/themes/UFAL/lib/js/messages/messages_de.js
• license: dspace/config/licenses/default.license -> dspace/config/licenses/alternative_de.license

3. Create a locale-specific subdirectory (e.g., dspace-xmlui/src/main/webapp/themes/UFAL/lib/html/de/) with a copy of your static HTML pages (at least those which require localisation).
4. Translate the XML messages, JS messages, license and static HTML pages.
5. Set the locale parameter value in the last line of the JS messages file (e.g., jQuery.i18n.load('de', messages);
6. Update your front-end appropriately (if using lindat-common, you probably want to add a language flag icon and translated versions of your footer and header).
7. Add the new locale to supported.locales in your local.properties.
8. Make a git pull request to include your XML/JS message and license translations in the main clarin-dspace branch (https://github.com/ufal/clarin-dspace/wiki/Code-contributions). (You may want to omit message keys that are specific to your installation, such as those used only in your static HTML files.)

Updating already localised installations

If you already localised your system before release 2017.04, most of your localisation should still work. However, you will probably need to update your JS messages in line with the new messages*.js system:

1. Create a JS message file (e.g., messages_de.js) (as described in step 2 above).
2. Set the locale in your messages_de.js (as in step 5 above).
3. Find all the i18n.load blocks in the other (non-message) JS files (e.g., dragndrop.js).
4. Look in messages.js to find which keys correspond to the English strings (which were used as keys before).
5. Replace the translations in messages_de.js with the appropriate ones from the other JS files.
6. Delete the i18n.load blocks from the other JS files.
7. Consider making a git pull request (as in step 8 above).

Checking for message key changes when upgrading

When upgrading your clarin-dspace repository to a new release, there may be new or changed message keys (XML and/or JS) needing translation. You can check for missing translations with check-message-translations.py, specifying the target locale and (optionally, defaulting to en) source locale:

$ python utilities/project_helpers/scripts/check-message-translations.py de

There is also a script which checks for missing and superfluous keys relative to what is referenced in the code (although this is not totally reliable since some keys are generated dynamically):

$ python utilities/project_helpers/scripts/check-message-usages.py de