How to Translate Sakai

How to Start

Anyone interested in localizing/translating Sakai is strongly encouraged to join the "I18N and L10N" worksite in http://collab.sakaiproject.org/portal. Resources and email lists are available at this site. I would recommend that you read this entire page before proceeding.

If you are planning on working on a Sakai translation, please send me an email (beth.kirschner at umich.edu). There may be someone else already working on translating Sakai to your target language.

Sun provides some general guides to translation at the Open Translation Website.

Before you can begin with the translation process, you will need to install and build Sakai from source. Directions can be found at Sakai Release Page (look for the Installation Guide in the Documentation section).

Translating is a tedious job, and perhaps best to translate tool-by-tool. Try to do a cursory look over as many of the tool pages as possible to verify the correctness of the translation in context. If a translation doesn't look right, you can identify which property is mis-translated by selecting the 'en_DEBUG' language locale in user preferences (see below, Translation Help). Most tools (though not components) can be re-loaded without needing to restart tomcat, which can help with turn-around time when fixing up translations.

What to Translate

All of the localized text (ready for translation) resides in either HTML files or source-code "properties" files containing key=value pairs.

Properties files values should be translated into locale-specific files, for example a Spanish language version of a properties file would be calendar_es.properties.
Not all properties files contain localized text (some are configuration files). A nice list of configuration files to exclude is at http://qa1-nl.sakaiproject.org/international/trunk/de.html#excludedfiles
Help text is referenced from help.xml files located with each tool. In order to translate, a locale-specific help.xml file should be created (e.g. help_fr_CA.xml), which references the translated HTML help text. Note that a complete set of help.xml files must be created for the translated locale.
Alternate HTML content locations can be configured in sakai.properties:

server.info.url=/library/content/server_info_LOCALE.html
myworkspace.info.url=/library/content/myworkspace_info_LOCALE.html
webcontent.instructions.url=/library/content/webcontent_instructions_LOCALE.html
webdav.instructions.url=/library/content/webdav_instructions_LOCALE.html

Sun keeps a list of supported locales at http://java.sun.com/j2se/1.5.0/docs/guide/intl/locale.doc.html (if your locale isn't listed, we can create one for you). All translated text must be saved as ascii-encoded UTF-8 characters; the suggested tools below will do this for you.

Page and Tools titles are localized in the tools.properties file:

sakai/tool/tool-impl/impl/src/bundle/tools.properties (Sakai 2.5.x)
sakai/config/localization/bundles/src/bundle/org/sakaiproject/localization/bundle/tool/tools.properties (Sakai 2.6.x)

There is still a small amount of text that has not been localized (e.g. permissions), but these are being worked on.

Suggested Translation Tools

The ResourceProperties Editor is a platform-independent, downloadable tool which supports editing and translating properties files. Its available from http://sourceforge.net/projects/i18nedit with documentation at http://i18nedit.sourceforge.net/userdoc/. This editor keeps track of changes, additions, and deletions to the default bundle, allowing translations to easily be kept up to date. UTF-8 characters can be typed directly into the editor, and they will be automatically asci-encoded when the file is saved. Note: You may need to create an i18n.properties file in the root of your Sakai directory for this tool to work. The file should contain the following two lines (the second line should include the language/locale you will be translating):

locale.default=en
locales=de fr ru (or similar))

The PropertyTransferer is a web-based GUI utility from Smolny College of Liberal Arts and Sciences (St. Petersburg, Russia) to transfer property values from one property list to another, for updating localization files to the newer version. The latest version is available as a web-based tool at http://pt.smolny.nw.ru/ (the source is also available from https://source.sakaiproject.org/contrib/tools/i18n/property-transfer/).

The XLIFF Translation Editor is also a platform-independent, stand-alone tool which supports editing and translating a wide variety of file types. While it doesn't track changes like the ResourceProperties Editor, it does provide many other features which makes it a powerful tool for translating help pages and other HTML-based pages within Sakai.

Translation Help

One way to discover the context of properties keys (i.e. where is the property key displayed on the page) is to enable a special debugging (en_DEBUG) locale by adding the following to sakai.properties

locales = en, ja_JP, ko_KR, nl_NL, zh_CN, es_ES, fr_CA, ca_ES, en_GB, ar, en_DEBUG

Once this has been added and Sakai restarted, you can select the en_DEBUG locale within your user preferences to display the actual key value in place of the translated text.

Another option is to enable debugging in the ResourceLoader by adding the following to sakai.properties

log.config.count = 1
log.config.1 = DEBUG.org.sakaiproject.util.ResourceLoader

Logging message examples (warning: this is noisy, but useful for translation/context information):

DEBUG: getString(key) bundle name=announcement, locale=en_US, key=view.all, value=All (2008-01-15 14:55:04,546 http-8080Processor25_org.sakaiproject.util.ResourceLoader)
DEBUG: getString(key) bundle name=announcement, locale=en_US, key=view.public, value=Public (2008-01-15 14:55:04,546 http-8080Processor25_org.sakaiproject.util.ResourceLoader)
DEBUG: getString(key) bundle name=announcement, locale=en_US, key=gen.thereare, value=There are currently no announcements at this location.(2008-01-15 14:55:04,550 http-8080-Processor25_org.sakaiproject.util.ResourceLoader)

After Translating

The translated properties files need to be in the source directories with the appropriate language extension (this is important). For example, sakai/discussion/discussion-tool/tool/src/bundle/discussion.properties translated into Japanese wouldbe copied to sakai/discussion/discussion-tool/tool/src/bundle/discussion_ja.properties. If you use the above ResourceProperties Editor, this will be done for you.
Next step would be to fully build and deploy Sakai, as described in the Source Installation Guide.
The default language locale for Sakai should be set either in Tomcat's catalina.sh (or catalina.bat) file or using "Preferences" after Sakai has started.

The JAVA_OPTS environment variable specifies the language locale at startup. Following is an example that sets Japanese as the default language in the catalina.sh file:
JAVA_OPTS="$JAVA_OPTS -Duser.language=ja -Duser.region=JP"
The locales variable in the sakai.properties file specifies which locales are available in the "Preferences" tool. The following is the default value:
locales = en, ja_JP, ko_KR, nl_NL, zh_CN, es_ES, fr_CA, ca_ES, en_GB, ar

Now you can start up Sakai! Any strings which have not been translated will use the default Resource Bundles (which are in English).

Adding Translations to Sakai Source

Once you've verified the translation, please contact me (beth dot kirschner at umich dot edu) so that they can be checked into source control and made available to the rest of the Sakai community. If you haven't signed a CCLA/CLA license for Sakai, please include the following at the top of every properties file:

#
# Copyright (c) 2008 Sakai Foundation
#
# Licensed under the Educational Community License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.osedu.org/licenses/ECL-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

Alternately, those who have signed (open source) license agreements with the Sakai Foundation, may be given Subversion Commit Privilege for properties bundles.