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.
2. 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.
12th Sakai Conference – Los Angeles, California – June 14-16 2
3. 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
12th Sakai Conference – Los Angeles, California – June 14-16 3
4. 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
12th Sakai Conference – Los Angeles, California – June 14-16 4
5. 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/Ho
me (for more)
12th Sakai Conference – Los Angeles, California – June 14-16 5
6. 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
12th Sakai Conference – Los Angeles, California – June 14-16 6
7. 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
12th Sakai Conference – Los Angeles, California – June 14-16 7
8. 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.
12th Sakai Conference – Los Angeles, California – June 14-16 8
9. 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/b
undle/EvaluationMessages.properties
●
paging_status=Viewing {0} - {1} of {2} items
12th Sakai Conference – Los Angeles, California – June 14-16 9
10. 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/
12th Sakai Conference – Los Angeles, California – June 14-16 10
11. Use in Java code
●
Static phrase
ResourceLoader rb = new
ResourceLoader("_org.sakaiproject.tool.foobar
.bundle.Messages_");
String foo = rb.getString("foo");
●
Dynamic phrase
String s
=rb.getFormattedMessage("event.syllabus.de
lete", new Object[]
{syllabusData.getTitle(),siteId});
12th Sakai Conference – Los Angeles, California – June 14-16 11
12. 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
12th Sakai Conference – Los Angeles, California – June 14-16 12
13. 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>
12th Sakai Conference – Los Angeles, California – June 14-16 13
14. 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>
12th Sakai Conference – Los Angeles, California – June 14-16 14
15. Use in Velocity based tools
● Pass Sakai CLE's ResourceLoader to your
velocity template
ResourceLoader rb = new
ResourceLoader("_org.sakaiproject.tool.foobar.bun
dle.Messages_");
context.put("tlang", rb );
● Static string
$tlang.getString("foo");
● Dynamic string
$tlang.getFormattedMessage("foo", $value);
12th Sakai Conference – Los Angeles, California – June 14-16 15
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/s
itesetupgeneric"/>
<property name="cacheSeconds" value="10" />
</bean>
12th Sakai Conference – Los Angeles, California – June 14-16 16
17. Use in RSF based tools (2/2)
●
Static string
UIMessage.make(tofill, "my-rsf-id",
"page.user.message.key");
●
Dynamic string
UIMessage.make(tofill, "modify-template-
header",
"modifyemail.modify.template.header",
new Object[] {headerName});
12th Sakai Conference – Los Angeles, California – June 14-16 17
18. 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().addStringResourceLoa
der(new MyStringResourceLoader());
12th Sakai Conference – Los Angeles, California – June 14-16 18
19. 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);
12th Sakai Conference – Los Angeles, California – June 14-16 19
20. 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 string
var removalString = fluid.messageLocator( messageBundle )
(["administrate.general.enable.response.removal"]);
● Dynamic string
var removalString = fluid.messageLocator( messageBundle )
(["removeitem.removed.user.message"], 3 );
12th Sakai Conference – Los Angeles, California – June 14-16 20
21. 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
12th Sakai Conference – Los Angeles, California – June 14-16 21
22. Use in other frameworks
●
If other frameworks are used,
further documentation should be
provided
●
Trimpath documentation has
started recently
12th Sakai Conference – Los Angeles, California – June 14-16 22
23. 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)
12th Sakai Conference – Los Angeles, California – June 14-16 23
24. 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?”
12th Sakai Conference – Los Angeles, California – June 14-16 24
25. 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
12th Sakai Conference – Los Angeles, California – June 14-16 25
26. 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.
12th Sakai Conference – Los Angeles, California – June 14-16 26
27. 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
12th Sakai Conference – Los Angeles, California – June 14-16 27