Oracle ADF Architecture TV - Design - Designing for Internationalization

1 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.


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


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



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




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



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

c7 N/A

N/A N/A 82

41

e3 81

87 c3

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



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



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

Technology

Oracle ADF Architecture TV - Design - Designing for Internationalization