practical internationalization improvement for sakai cle
DESCRIPTION
If you write or maintain code, you most likely will have or already have internationalization issues, even if you're not already aware of it. They will be numerous if you've not read the available guidelines and been very careful. Even if you have, to err is human, and we could still find a few. After getting rid of the errors, there are still improvements that might help translators' work. This workshop's goal is to explain reasons behind guidelines, do hands-on improvement of real-life code and improve the available guidelines.TRANSCRIPT
Practical Internationalization Improvement for Sakai CLE
Jean-François Lévêque, Developer, UPMCwith content from Beth Kirschner,
i18n/L10n contributors and developers
P.I.I. definition (from Wiktionary)
● Practical● Based on practice or action rather than theory or
hypothesis
● Internationalization● The act or process of making a product suitable for
international markets
● Improvement● The act of improving; advancement or growth;
promotion in desirable qualities; progress toward what is better; melioration
● Sakai CLE only? I don't know OAE much.
212th Sakai Conference – Los Angeles, California – June 14-16
Internationalization and localization (from Wikipedia)● means of adapting computer software to
different languages, regional differences and technical requirements of a target market
● Internationalization (i18n)● process of designing a software application so
that it can be adapted to various languages and regions without engineering changes
● Localization (L10n)● process of adapting internationalized software for
a specific region or language by adding locale-specific components and translating text
312th Sakai Conference – Los Angeles, California – June 14-16
What's in a locale?
● Language (ISO Language Code)● ar, eu, ca, zh, nl, en, fr, ja, ko, pt, ru, es, sv, tr, vi
● Country (ISO Country Code)● ES, CN, TW, NL, AU, NZ, ZA, GB, US, CA, FR, JP,
KR, BR, PT, RU, SE, TR, VN
● Variant (free)● DEBUG (in en_US_DEBUG)
● Check java.util.Locale for more
412th Sakai Conference – Los Angeles, California – June 14-16
CLE focal i18n points (my choice)
● Alphabets/scripts: Unicode with UTF-8
● Writing direction: customized skins or CSS
● Graphical representations of text: to avoid
● Date/time format
● Time zones
● Formatting of numbers
● Displayable strings
● https://confluence.sakaiproject.org/display/I18N/Home (for more)
512th Sakai Conference – Los Angeles, California – June 14-16
Date/time with TZ and numbers
● Localize Date & Time● Output: java.text.DateFormat (has Time Zone)● Input (don't forget the Time Zone):
– java.text.DateFormat's parse– Date/time widget with i18n
● Localize numbers● Output: java.text.NumberFormat/DecimalFormat● Input: java.text.NumberFormat/DecimalFormat's
parse
612th Sakai Conference – Los Angeles, California – June 14-16
Displayable strings
● Use org.sakaiproject.util.ResourceLoader● Static phrases:
● language based text should be localized into a properties file
● Dynamic phrases:● still in properties file● use getFormattedMessage● structure messages appropriately
712th Sakai Conference – Los Angeles, California – June 14-16
Other strings
● Properties files (<filename>.properties) should only be used for user interface text that should be translated.● All other configuration information (e.g. configuration
constants, class names, filenames, etc.) should be in a separate directory tree.
● Alternately, config files can use the <filename>.config extension
● Properties files should not have mixed content and contain explicit information about their content. This information should be also provided in the tool documentation.
812th Sakai Conference – Los Angeles, California – June 14-16
Sample .properties entries
● shortenedurl/impl/src/java/url.properties● url = An entity provider to allow shortening of
URLs via the ShortenedUrlService● samigo/samigo-
app/src/java/org/sakaiproject/tool/assessment/bundle/EvaluationMessages.properties● paging_status=Viewing {0} - {1} of {2} items
912th Sakai Conference – Los Angeles, California – June 14-16
More about i18n .properties
● Do not keep unused key/value pairs● Double check you don't concatenate strings● Do not use several keys for the same value● Please reuse labels (button, tool name ...) when
used in other strings● Do not use the \ to escape the line terminator
sequence in properties files. This is a source of human errors, prevents sorting and is not compatible with loi's l10n-stats currently used in http://qa1-nl.sakaiproject.org/international/
1012th Sakai Conference – Los Angeles, California – June 14-16
Use in Java code
● Static phraseResourceLoader rb = new ResourceLoader("_org.sakaiproject.tool.foobar.bundle.Messages_");
String foo = rb.getString("foo");
● Dynamic phraseString s =rb.getFormattedMessage("event.syllabus.delete", new Object[]{syllabusData.getTitle(),siteId});
1112th Sakai Conference – Los Angeles, California – June 14-16
Use in JSF based tools
● Static phrase<h:outputText value="#{msgs.foo}"/>
● Dynamic phrase<h:outputFormat value="#{msgs.lay_restricted_note_messages}" rendered="#{ChatTool.canRenderNumberMessages}" >
● Use Sakai CLE's ResourceLoader for i18n bundles
1212th Sakai Conference – Los Angeles, California – June 14-16
Use in JSP based tools (1/2)
● Use Sakai CLE's ResourceLoader to get the locale and load bundles
<jsp:useBean id="msgs" class="org.sakaiproject.util.ResourceLoader" scope="session">
<jsp:setProperty name="msgs" property="baseName" value="messages"/>
</jsp:useBean>
1312th Sakai Conference – Los Angeles, California – June 14-16
Use in JSP based tools (2/2)
● Static phrase<c:out value="${msgs.foo}"/>
● Dynamic phrase<fmt:message key="message_permissionsEdit">
<fmt:param><c:out value="${tool.title}"/></fmt:param>
<fmt:param><c:out value="${worksite.title}"/></fmt:param>
</fmt:message>
1412th Sakai Conference – Los Angeles, California – June 14-16
Use in Velocity based tools
● Pass Sakai CLE's ResourceLoader to your velocity template
ResourceLoader rb = new ResourceLoader("_org.sakaiproject.tool.foobar.bundle.Messages_");
context.put("tlang", rb );
● Static string$tlang.getString("foo");
● Dynamic string$tlang.getFormattedMessage("foo", $value);
1512th Sakai Conference – Los Angeles, California – June 14-16
Use in RSF based tools (1/2)
● Use CLE's ResourceLoaderMessageSource
<bean id="messageSource"
class="org.sakaiproject.util.ResourceLoaderMessageSource">
<property name="basename" value="classpath:org/sakaiproject/site/tool/participant/bundle/sitesetupgeneric"/>
<property name="cacheSeconds" value="10" />
</bean>
1612th Sakai Conference – Los Angeles, California – June 14-16
Use in RSF based tools (2/2)
● Static stringUIMessage.make(tofill, "my-rsf-id", "page.user.message.key");
● Dynamic stringUIMessage.make(tofill, "modify-template-header", "modifyemail.modify.template.header", new Object[] {headerName});
1712th Sakai Conference – Los Angeles, California – June 14-16
Use in Wicket based tools (1/2)
● Implement your own ResourceLoader to take advantage of Sakai CLE's ResourceLoader
● Set it up in your WebApplication init method
getResourceSettings().addStringResourceLoader(new MyStringResourceLoader());
1812th Sakai Conference – Los Angeles, California – June 14-16
Use in Wicket based tools (2/2)
● Static string<wicket:message key="some.message.key" />
or
<table wicket:message="summary:my.great.table.message.key">
● Dynamic string (works for static too)Label myLabel = new Label("myLabel", new StringResourceModel("some.message.key.with.params", null, new Object[]{ value1, value2 } ));
someComponent.add(myLabel);
1912th Sakai Conference – Los Angeles, California – June 14-16
Use in Javascript based tools
● http://tinyurl.com/yhora2v● In a nutshell
● Use EntityBroker to call ResourceLoader, use Fluid Infusion, call the EntityProvider via AJAX request
● Static stringvar removalString = fluid.messageLocator( messageBundle )(["administrate.general.enable.response.removal"]);
● Dynamic stringvar removalString = fluid.messageLocator( messageBundle )(["removeitem.removed.user.message"], 3 );
2012th Sakai Conference – Los Angeles, California – June 14-16
Use in Google Web Toolkit (GWT) based tools
● GWT has its own i18n dev guide● Integrating GWT tools with Sakai
CLE Internationalization is still a work in progress
● No code using GWT in the official Sakai CLE so far
2112th Sakai Conference – Los Angeles, California – June 14-16
Use in other frameworks
● If other frameworks are used, further documentation should be provided
● Trimpath documentation has started recently
2212th Sakai Conference – Los Angeles, California – June 14-16
Static HTML files
● Provide automatic loading of translated files when provided (variant, country, language) for set locale (server_info_ja.html instead of
server_info.html)● Provide a documented debug file
giving translation instructions (webcontent_instructions_en_US_DEBUG.html
for webcontent_instructions.html)2312th Sakai Conference – Los Angeles, California – June 14-16
What else should I do?
● Document your i18n● List all the i18n properties files● List all the other files (HTML, XML, ...) that
have static or dynamic text which is displayed and explain how to translate them
● Document the way you're doing i18n if it's not documented in:
https://confluence.sakaiproject.org/display/I18N
● Answer “Am I using Sakai's ResourceLoader?”
2412th Sakai Conference – Los Angeles, California – June 14-16
Why should I use Sakai CLE's ResourceLoader?
● Provided en_US_DEBUG locale helps translation, otherwise you should mimic it
● Compatibility with the contrib message bundle editing tool
2512th Sakai Conference – Los Angeles, California – June 14-16
What else can I do?
● Please use EmailTemplateService to enable translation of whole emails with dynamic parts
● Check if you use the same strings as another tool.● If it's the case, contact me about shared
i18n.
2612th Sakai Conference – Los Angeles, California – June 14-16
How good is my tool?
● If it's part of the official release● Check for reported i18n issues
https://confluence.sakaiproject.org/display/SPANISH/i18n+tools+status
● Ask for a review by volunteers on i18n list
● If it's in contrib● And JIRA: ask for inclusion in i18n report● Review by volunteers is also possible
● Need help? Please ask
2712th Sakai Conference – Los Angeles, California – June 14-16