practical internationalization improvement for sakai cle

27
Practical Internationalization Improvement for Sakai CLE Jean-François Lévêque, Developer, UPMC with content from Beth Kirschner, i18n/L10n contributors and developers

Upload: jfl101010

Post on 05-Dec-2014

1.080 views

Category:

Technology


1 download

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

Page 1: 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

Page 2: Practical Internationalization Improvement for Sakai CLE

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

Page 3: Practical Internationalization Improvement for Sakai CLE

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

Page 4: Practical Internationalization Improvement for Sakai CLE

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

Page 5: Practical Internationalization Improvement for Sakai CLE

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

Page 6: Practical Internationalization Improvement for Sakai CLE

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

Page 7: Practical Internationalization Improvement for Sakai CLE

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

Page 8: Practical Internationalization Improvement for Sakai CLE

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

Page 9: Practical Internationalization Improvement for Sakai CLE

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

Page 10: Practical Internationalization Improvement for Sakai CLE

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

Page 11: Practical Internationalization Improvement for Sakai CLE

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

Page 12: Practical Internationalization Improvement for Sakai CLE

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

Page 13: Practical Internationalization Improvement for Sakai CLE

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

Page 14: Practical Internationalization Improvement for Sakai CLE

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

Page 15: Practical Internationalization Improvement for Sakai CLE

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

Page 16: Practical Internationalization Improvement for Sakai CLE

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

Page 17: Practical Internationalization Improvement for Sakai CLE

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

Page 18: Practical Internationalization Improvement for Sakai CLE

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

Page 19: Practical Internationalization Improvement for Sakai CLE

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

Page 20: Practical Internationalization Improvement for Sakai CLE

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

Page 21: Practical Internationalization Improvement for Sakai CLE

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

Page 22: Practical Internationalization Improvement for Sakai CLE

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

Page 23: Practical Internationalization Improvement for Sakai CLE

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

Page 24: Practical Internationalization Improvement for Sakai CLE

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

Page 25: Practical Internationalization Improvement for Sakai CLE

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

Page 26: Practical Internationalization Improvement for Sakai CLE

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

Page 27: Practical Internationalization Improvement for Sakai CLE

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