More Related Content Similar to Oracle ADF Architecture TV - Design - Designing for Internationalization (20) Oracle ADF Architecture TV - Design - Designing for Internationalization1. 1 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
2. 2 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Real World ADF Design & Architecture Principles
Designing for Internationalization
15th Feb 2013 v1.0
3. 3 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Learning Objectives
• At the end of this module you should be able to:
– Explain the concepts behind software
internationalization and the challenges it poses
– Evaluate the impact of internationalization requirements on a
software architecture
– Make architectural decisions related to internationalization in the
context of your own projects and justify them.
– Apply some ADF techniques described herein
Image: imagerymajestic/ FreeDigitalPhotos.net
4. 4 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
A Real Life Situation
You are visiting Brussels. Your Belgian friend who works in IT, says in French:
Il
paraît
que
Oracle
ADF
release
12c
est
terrible.
Which
translates
to
I
heard
Oracle
ADF
release
12c
is
terrible.
How would you
react?!
5. 5 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Another Real Life Situation
You have been working on an architecture document for weeks. You
finally completed your first draft and sent it for review. You are
exhausted, but proud to finally have delivered something. Your
Indian colleague comes to your office and says:
I
have
some
doubts
about
your
document. How would you
react?!
6. 6 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• What is Internationalization?
• User Interface Design
• Character Encoding
• Resource Bundles
• Time Zones
7. 7 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Internationalization (I18N): The design and
development of a product, application or document
content that enables easy localization for target
audiences that vary in culture, region, or language.
W3C, “ Localization vs Internationalization ”
http://tinyurl.com/i18nVSl10n
8. 8 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Localization (I10N): […] The adaptation of a product,
application or document content to meet the language,
cultural and other requirements of a specific target
market (a locale).
W3C, “ Localization vs Internationalization ”
http://tinyurl.com/i18nVSl10n
9. 9 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Solid fundamentals
• System
adapted
or
converted
to
a
specific
locale.
Localiza7on
• System
supports
mul7ple
languages
for
display
and
input,
but
possesses
a
single
fixed
UI
language.
Mul7lingualiza7on
• System
designed
for
use
in
a
range
of
locales.
• Extends
beyond
language
support
to
compliance
to
legisla7on
and
social
conven7ons
Interna7onaliza7on
10. 10 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Solid foundations
• Oracle ADF builds on the
robust internationalization
features found in Java
Standard Edition and Java
Enterprise Edition
• The semantics used in this
module are those of the Java
platform
ADF
Java
EE
Java
SE
11. 11 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Java Internationalization Vocabulary - Locale
• java.util.Locale Javadoc
“Represents a specific geographical, political, or cultural region”
• On the Java platform, possesses the following attributes:
– Language (ISO 639 code) ex: "en" (English), "ja" (Japanese)
– Script (ISO 15924) ex: "Latn" (Latin), "Cyrl" (Cyrillic)
– Country/region (ISO 3166) ex: "US”, "FR”, "029" (Caribbean)
– Variant
– Extensions
12. 12 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Locale and calendars
• Out of the box, the JVM supports the following calendars
Locale
Calendar
System
Since
(JRE
version)
th_TH
(with
any
variant)
Thai
Buddhist
calendar
1.4
ja_JP_JP
Japanese
imperial
calendar
1.6
Any
except
above
Locales
Gregorian
calendar
(GregorianCalendar)
1.1
13. 13 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Java Internationalization Vocabulary - Format
• The visual representation (format) and parsing of locale-sensitive
information such as dates, messages, and numbers
• A locale may support many formats, the locale defines a default
• Dates:
– Do not forget about the time zone
– See java.util.TimeZone
• Numbers:
– There’s no “ Money ” class in Java
– Use java.math.BigDecimal (ISO 4217) & java.util.Currency
14. 14 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Format: Currency and numbers
Country
Format
Currency
US
$12
Finland
Mk12
South
Korea
₩12
Germany
12DM
Country
Format
Numbers
US
1,234,567.89
Finland
1.234.567,89
South
Korea
1,234,567.89
Germany
1.234.567,89
15. 15 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.15 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
We have customers in all parts of the world.
Our ADF application must be
internationalized.
In order to support i18n, what parts of our
application do we have to change? Is it just
limited to ADF?
Exercise
Image: imagerymajestic/ FreeDigitalPhotos.net
16. 16 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
From Hardware to Software
Applica7on
User
Interface
Content
Infrastructure
App
Server
Database
OS
Hardware
Keyboard
The true scope of internationalization
17. 17 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• What is Internationalization?
• User Interface Design
• Character Encoding
• Resource Bundles
• Time Zones
18. 18 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Width of Words by Language
• The width of a word translated into different languages can vary
• Presents a challenge when designing the UI
• e.g. The comparative lengths of the word Flickr used for 'views' as a
ratio to the original English :
Source: W3C, Text Size in Translation. http://www.w3.org/International/articles/article-text-size
Language
Transla;on Ra;o
Korean
조회 0.8
English
views
1
Chinese
次檢視
1.2
Portuguese
visualizações
2.6
French
consulta7ons
2.6
German
-‐mal
angesehen
2.8
Italian
visualizzazioni
3
19. 19 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Translated Text Width Guidelines
• How much you must increase a static text field based on the number
of characters of English text:
Source: JD Edwards EnterpriseOne Tools Development Guidelines for Application Design Guide
Number
of
English
Characters Addi;onal
Space
Required
1
character 400
percent
or
4
characters
2—10
characters 101—200
percent
11—20
characters 81—100
percent
21—30
characters 61—80
percent
31—70
characters 31—40
percent
More
than
70
characters 30
percent
20. 20 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Languages and space use
• Never use unapproved abbreviations, acronyms or symbols as a
way to save space
• The default fonts for some languages provide bigger glyphs
(character shapes) than English
– Consumes more vertical and horizontal space.
• Some languages may not have equivalent terms to those used in
the original version
– Translation uses multiple words
• Some countries, such as Sweden, regard the active voice as
impolite, and use longer passive voice constructions
21. 21 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Advice on UI labels (1 of 2)
• Spell out contractions.
– Use "do not" instead of "don't."
• Do not use possessives in UI labels
– Use "file location" not "file's location."
• For compound actions, use "or" instead of a slash, and "and"
instead of an ampersand
• Do not use the construction "and/or":
– "and" and "or" are mutually exclusive, and translators may have difficulty
understanding which meaning is intended.
• Slashes should be used only in rare instances
– For direct opposites, such as "Yes/No" or "Mr./Ms." or "State/Region"
22. 22 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Advice on UI labels (2 of 2)
• Use complete phrases in labels
– Use "Replacement Text" instead of "Replace with"
• Do not rely on capitalization to indicate semantic differences
– Some languages do not have capital letters.
• Product names may also need to be translated
• When applicable, leave space between UI text and numbers
– A label for a multi-lined address should be labeled "Address Line 1", not "Address
line1"
23. 23 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Bidirectional Languages
• Most middle eastern languages, such as Hebrew and Arabic, are
written from right-to-left rather than left-to-right
• Numbers however are generally written from left to right in those
same languages
• Software that supports this is often referred to as having BIDI or Bi-
Directional language support
• This is fully supported by the Java platform and by extension ADF
24. 24 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.24 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
25. 25 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
UI design and Bidirectional Languages
• Web users spend 69% of their time viewing the left half of the page
and 30% viewing the right half
• Should we completely redesign our applications for markets using
bidirectional languages?
• Specialists say no, since foreigners adapt themselves to
applications built elsewhere
Source: Jakob Nielsen, “ Horizontal Attention Leans Left ”.
http://tinyurl.com/yawlk3x
26. 26 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• Here are some visual elements you may know
• Do you think they will be understood equally well in all cultures?
Culture and Visual Elements
27. 27 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Layout tips
• Avoid hard-coding widths, using text to balance or force layout
• Avoid forced breaks (<BR>, /t,  , …)
• Don’t force alignments to left or right
• Use the proper components for tables
• Reports in HTML, XML, not text
28. 28 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• What is Internationalization?
• User Interface Design
• Character Encoding
• Resource Bundles
• Time Zones
29. 29 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Why are we Talking about Encoding?
• Words and sentences are made from characters
• Characters are grouped into a character set
• Those are called coded character sets when each character is
assigned a specific number, called a code point
• These code points are represented in computers by one or more
bytes
• All characters are stored in computers using a code. A character
encoding is thus a key to decipher the code
30. 30 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Encoding and storage
• UTF-16: two-byte fixed-length encoding scheme
• UTF-8: variable length encoding scheme
UTF-8
Encoding
A
Latin1
CharSet
US-ASCII
CharSet
Character
41 41
c7N/A
N/A N/A
82
41
e3 81
87c3
UTF-16
Encoding
41
c7
30 42
00
00
English Alphabet
French Alphabet
Japanese
31. 31 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Character Encoding in a Web Application
Opera7ng
System
File
System
Dev
tools
Database
App
Server
JSF
pages
• There are several distinct
possible encodings in any
application
• Consistency is the key to
preserve data integrity
32. 32 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
About Your Database
• The Oracle database manages its own internationalization settings.
• Of these two are particularly important:
1. Character set: must support whatever applications will try to store.
• “Oracle recommends using Unicode for all new system
deployments” (AL32UTF8)
Source: Oracle® Database Globalization Support Guide
2. Sort order, which can be:
• Binary
• Monolingual
• Multilingual
33. 33 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
JDeveloper Source Code Encoding
• Preferences > Environment > Encoding defines the encoding of
JDeveloper source code on the file system
• This applies to new files only
• Set it before you start coding
• Make it standard across
developer machines
• Ensure the page and source
code encoding are in sync (by
default they’re not)
34. 34 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Compiler Output Encoding
• Accessible through Project
Properties > Compiler
• Must be supported by the
operating system on which the
target application server runs
35. 35 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
JSP / JSF Page Character Set Configuration
• The character set is defined at the top of each JSF page
• The user’s browser uses this to interpret how to show character
symbols
• Select a sensible value - UTF-8
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns:f="http://java.sun.com/jsf/core"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<af:document title="home.jsf" id="d1">
....
</af:document>
</f:view>
36. 36 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
JSP / JSF Page Character Set Configuration
• Done on each ViewController
project
• Go to Project Properties >
Compiler > JSP
• This will change the default
encoding for all new JSP / JSF
pages
• This doesn’t affect the file
encoding on the file system,
however
37. 37 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• What is Internationalization?
• User Interface Design
• Character Encoding
• Resource Bundles
• Time Zones
38. 38 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Resource Bundles
• Part of the Java EE platform
• Separate the UI text from the JSF pages
– Similar benefits to separating HTML from CSS
– Allows separate bundles to be swapped in based on user’s locale
– Defines key-value pairs for translatable content
• It is possible to override the resources defined in ADF’s resource
bundles. Simply find the keys for the strings you want to alter and
use them in your own bundles or through skinning.
39. 39 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Resource Bundle Fallback
• By default in a web application the locale is selected automatically
according to the language preference supplied by the browser
– If the preferred language isn’t available there is a transparent fallback
mechanism
• Example: If your browser is set to the French (Canada) locale and the
default locale of the application is US English, the application attempts
to find the closest match, looking in the following order:
– fr_CA
– fr
– en_US
– en
– Base class bundle
40. 40 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Resource Bundle Types
• Java class bundles
– Less flexible (recompile needed for changes to show)
– Seldom used by themselves; useful to read values from the database, for example
• .properties files
– Simplest and easiest alternative
– More compact than XML (since text files are less verbose)
• XLIFF
– OASIS standard (see http://docs.oasis-open.org/xliff/xliff-core/xliff-core.html)
– Integrates with a variety of third-party tools used by translators
• Use .properties files unless your translators use XLIFF-based tools
41. 41 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Resource Bundle Naming
• Use any name you like for the bundle representing the default
locale, e.g.:
– myBundle.java, myBundle.properties or myBundle.xlf
• Add a suffix with the appropriate locale code for other locales
• Use ISO 639 lowercase language code + ISO 3166
uppercase country code
• Only include the country code if it’s needed (such as the
following French Canadian example):
– myBundle_fr_CA.java, myBundle_fr_CA.properties,
myBundle_fr_CA.xlf
42. 42 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Bundle Configuration – faces-config.xml
• Declare supported locales
• Register bundles (for bundles not configured in project properties)
<locale-config>
<default-locale>en</default-locale>
<supported-locale>de</supported-locale>
<supported-locale>fr_CA</supported-locale>
</locale-config>
<resource-bundle>
<base-name>oracle.web.UIBundle</base-name>
<var>res</var>
</resource-bundle>
43. 43 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Binding to a Bundle
or
<af:commandButton
text="#{adfBundle['project.myBundle'] ['CART_EMPTY']}"
<af:commandButton
text="#{res['oracle.web.button.go']}"
44. 44 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
How Many Resource Bundles do I Need?
• Rule of thumb:
– ViewController project : 1 bundle per project.
– Model project: 1 bundle per file.
• However, it is possible to define a central bundle to host all common
entries if you have enough of them. To do so:
– Create a new bundle file matching the type selected for the project
– Reference it in the “ Bundle Search ” tab
45. 45 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Defining a Central Bundle for Common Entries
46. 46 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Database as a Resource Bundle
• It is possible to place resources in the database instead of bundles
• Pros:
– You can change the UI text without redeploying the application
– It is possible to build screens to manage the text that will take care of
character escaping (But JDev does this for you)
• Cons:
– Import of the text required when new translations are provided
– Distinct deployments of the same version of the application could have
different text for the same UI elements
• The real question is: how often will the text resources change?
47. 47 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Database as a Resource Bundle
1. Create a table to hold the text
2. At a minimum, the columns should include: locale code, key, value
3. Create an ADF view object to access the data (and optionally
entity objects if the application will write to the table)
4. Create a class inheriting from java.util.ListResourceBundle.
5. In that class, implement the Object[][] getContents
abstract method and use the VO created at step 2 to read the
bundle entries.
6. Reference the class in the “ Bundle Search ” tab of the “ Resource
Bundle ” section on the project properties.
48. 48 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Internationalization and Skinning
• ADF Skinning fully supports Internationalization
• Be aware:
– JDeveloper Skinning Editor supports .properties files only (it won’t give
you a choice)
– Text in images cannot be translated
– Icons and pictograms may not have the same meaning across cultures
and generations
– The :rtl pseudo-class renders ADF Faces components from right to left
– Other pseudo-classes can be useful for internationalization
49. 49 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Internationalization and Skinning
• Tip: You can select a skin according to the active locale by using EL
in the trinidad-config.xml file
<skin-family>
#{view.locale.language == 'en' ? 'normalSkin' : 'customSkin'}
</skin-family>
50. 50 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Changing the Locale Dynamically
• Sometimes, users cannot alter browser settings to suit their own
language preferences or desire to select a specific language in the
application without changing their browser settings. You have two
options at your disposal to accommodate this requirement
• Option 1: Bind the locale attribute of the f:view tag to a
managed bean
• Option 2: Build a custom JSF view handler and override the Locale
calculateLocate(FacesContext context)method
51. 51 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Application Data
• Don’t forget that Internationalization deals with the application’s UI,
not its data
• You need to design the application in the appropriate way to support
multilingual data
– Adding a locale column to specific tables and updating the model layer
accordingly
– Putting user content (such as articles, comments and documents) in a
proper content management system, such as Oracle WebCenter
Content, thus helping support the translation workflow
52. 52 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
“Help” Internationalization
• Don’t forget to localize the system “help”
• ADF Supports several help content providers based on:
– Resource Bundles (.properties)
– XLIFF files
– Managed beans
• You can also use Oracle Help, which supports localized content and
offers an “ADF Rich Client Help Provider”
53. 53 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• What is Internationalization?
• User Interface Design
• Character Encoding
• Resource Bundles
• Time Zones
54. 54 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
About Timezones
• The java.util.Date class can keep track of time zones
• It is better to use java.util.Calendar and its descendants to
manipulate dates
• Date input/output formats are determined by the locale, but it is
possible to specify them (or the locale)
• Be careful with SYSDATE; it will give you the database server’s date
and time zone.
55. 55 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Time Zone Strategies
• Choosing a time zone strategy for an application is a matter of
corporate policy. Customer requirements could be implementable
technically but run afoul of the policy. It is thus essential to ensure
conformity before implementing anything.
• For reference, Fusion Applications offer three distinct strategies:
– Corporate Reporting Time Zone - displays the server time zone
– User Preferred Time Zone - displays the user preferred time zone
– Legal Entity Time Zone - displays the arbitrary time zone associated with a legal
entity
56. 56 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
af:inputDate and Time Zones
• Suppose you put the following in a page or fragment:
• On the page, you get this:
• But in the database, you get:
A subtle problem
<af:inputDate …>
<f:validator binding="#{bindings.Modified.validator}"/>
<af:convertDateTime pattern="yyyy-MM-dd 'at' HH:mm:ss z" type="both"/>
</af:inputDate>
57. 57 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
af:inputDate and Time Zones
“Developers should note that on the Javascript peer, the value
returned is always in the user's timezone, even if the user has
selected a different timezone in the picker. This is because Javascript
does not provide information on timezone offsets of a different
timezone.”
Source: Oracle Fusion Middleware Tag Reference for Oracle ADF Faces,
http://docs.oracle.com/cd/E35521_01/apirefs.111230/e17491/tagdoc/af_inputDate.html
Why is this happening?
58. 58 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
af:inputDate and Time Zones
• Option #1: do not select the time through a picker but use an
alternate control and some Java logic.
• Option #2: specify a static or EL value in trinidad-config.xml
Mitigation Strategies
<!-- Set the time zone to Pacific Daylight Savings Time -->
<time-zone>PDT</time-zone>
59. 59 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.59 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Exercise
Image: imagerymajestic/ FreeDigitalPhotos.net
When should we start
internationalization work
on our project?
60. 60 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Selecting the Locale of ADF Error Messages
• By default ADF will output its error messages in the selected locale
for the operating system account the app server runs on
• You can change this via the following JVM parameters:
• Can be added to the WebLogic startup scripts for a more global
result. See setDomainEnv.sh (or .cmd)
-Duser.language=en -Duser.country=US
61. 61 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Further reading
• OTN: Java Internationalization
– http://tinyurl.com/otn-java-i18n
• W3C’s Internationalization home page
– http://www.w3.org/International/
• Ultan Ó Broin’s blog
– http://blogs.oracle.com/translation
• Oracle Applications User Experience
– http://tinyurl.com/apps-ux
• Apple’s iOS Human Interface Guidelines
– http://tinyurl.com/apple-ios-hig
62. 62 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.