Download - Practical Internationalization Improvement for Sakai CLE

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


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


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)


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


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


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.


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


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/


http://qa1-nl.sakaiproject.org/international/

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});


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


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>


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>


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);


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>


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});


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());


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);


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 );


http://tinyurl.com/yhora2v

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


Use in other frameworks

● If other frameworks are used, further documentation should be provided

● Trimpath documentation has started recently


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?”


https://confluence.sakaiproject.org/display/I18N

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


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.


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


https://confluence.sakaiproject.org/display/SPANISH/i18n+tools+status