Oracle ADF Architecture TV - Design - Designing for Internationalization

Real World ADF Design & Architecture Principles
Designing for Internationalization
15th Feb 2013 v1.0

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

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

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

Program Agenda
•  What is Internationalization?
•  User Interface Design
•  Character Encoding
•  Resource Bundles
•  Time Zones

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

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

Solid fundamentals
•  System
adapted
or
converted
to
a
speciﬁc
locale.
Localiza7on

•  System
supports
mul7ple
languages
for
display

and
input,
but
possesses
a
single
ﬁxed
UI

language.

Mul7lingualiza7on

•  System
designed
for
use
in
a
range
of
locales.

•  Extends
beyond
language
support
to
compliance

to
legisla7on
and
social
conven7ons

Interna7onaliza7on

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

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

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

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

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

From Hardware to Software
Applica7on

User

Interface

Content

Infrastructure

App
Server

Database

OS

Hardware

Keyboard

The true scope of internationalization

Program Agenda
•  Time Zones

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

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

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

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"

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"

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

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

•  Here are some visual elements you may know
•  Do you think they will be understood equally well in all cultures?
Culture and Visual Elements

Layout tips
•  Avoid hard-coding widths, using text to balance or force layout
•  Avoid forced breaks (<BR>, /t, &nbsp, …)
•  Don’t force alignments to left or right
•  Use the proper components for tables
•  Reports in HTML, XML, not text

Program Agenda
•  Time Zones

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

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

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

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

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)

Compiler Output Encoding
•  Accessible through Project
Properties > Compiler
•  Must be supported by the
operating system on which the
target application server runs

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>

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

Program Agenda
•  Time Zones

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.

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

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

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

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>

Binding to a Bundle
or
<af:commandButton
text="#{adfBundle['project.myBundle'] ['CART_EMPTY']}"
<af:commandButton
text="#{res['oracle.web.button.go']}"

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

Defining a Central Bundle for Common Entries

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?

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.

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

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>

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

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

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

Program Agenda
•  Time Zones

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.

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

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>

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

•  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

<time-zone>PDT</time-zone>

Exercise
When should we start
internationalization work
on our project?

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

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

Oracle ADF Architecture TV - Design - Designing for Internationalization

More Related Content

What's hot

Similar to Oracle ADF Architecture TV - Design - Designing for Internationalization

Recently uploaded

Oracle ADF Architecture TV - Design - Designing for Internationalization