Translating Your Customizations
- by Richard Bingham
This blog post explains the basics of translating the customizations
you can make to Fusion Applications products, with the inclusion of
information for both composer-based customizations and the generic
design-time customizations done via JDeveloper.
Introduction
Like most Oracle Applications, Fusion Applications installs
on-premise with a US-English base language that is, in Release 7,
supported by the option to add up to a total of 22 additional language packs
(In Oracle Cloud production environments languages are pre-installed
already). As such many organizations offer their users the option of
working with their local language, and logically that should also apply
for any customizations as well.
Composer-based UI Customizations
Customizations made in Page Composer take into consideration the
session LOCALE, as set in the user preferences screen, during all
customization work, and stores the customization in the MDS repository
accordingly. As such the actual new or changed values used will only
apply for the same language under which the customization was made, and
text for any other languages requires a separate upload. See the
Resource Bundles section below, which incidentally also applies to
custom UI changes done in JDeveloper.
You may have noticed this when you select the “Select Text Resource”
menu option when editing the text on a page. Using this ensures that the
resource bundles are used, whereas if you define a static value in
Expression Builder it will never be available for translation. Notice in
the screenshot below the “What’s New” custom value I have already
defined using the ‘Select Text Resource’ feature is internally using the
adfBundle groovy function to pull the custom value for my key (RT_S_1) from the ComposerOverrideBundle.
Figure 1 – Page Composer showing the override bundle being used.
Business Objects
Customizing the Business Objects available in the Applications
Composer tool for the CRM products, such as adding additional fields,
also operates using the session language. Translating these additional
values for these fields into other installed languages requires loading
additional resource bundles, again as described below.
Reports and Analytics
Most customizations to Reports and BI Analytics are just essentially
reorganizations and visualizations of existing number and text data from
the system, and as such will use the appropriate values based on the
users session language. Where a translated value or string exists for
that session language, it will be used without the need for additional
work.
Extending through the addition of brand new reports and analytics
requires another method of loading the translated strings, as part of
what is known as ‘Localizing’ the BI Catalog and Metadata. This time it
is via an export/import of XML data through the BI Administrators
console, and is described in the OBIEE Admin Guide.
Fusion Applications reports based on BI Publisher are already defined
in template-per-locale, and in addition provide an extra process for
getting the data for translation and reloading. This again uses the
standard resource bundle format. Loading a custom report is illustrated
in this video from our YouTube channel which shows the screen for both setting the template local and running an export for translation.
Fusion Applications Menus
Whilst the seeded Navigator and Global Menu values are fully
translated when the additional language is installed, if they are
customized then the change or new menu item will apply universally, not
currently per language. This is set to change in a future release with
the new UI Text Editor feature described below.
More on Resource Bundles
As mentioned above, to provide translations for most of your
customizations you need to add values to a resource bundle. This is an
industry open standard (OASIS) format XML file with the extension
.xliff, and store translated values for the strings used by ADF at
run-time. The general process is that these values are exported from the
MDS repository, manually edited, and then imported back in again.This
needs to be done by an administrator, via either WLST commands or
through Enterprise Manager as per the screenshot below. This is detailed
out in the Fusion Applications Extensibility Guide. For SaaS environments the Cloud Operations team can assist.
Figure 2 – Enterprise Manager’s MDS export used getting resource
bundles for manual translation and re-imported on the same screen.
All customized strings are stored in an override bundle (xliff file)
for each locale, suffixed with the language initials, with English ones
being saved to the default. As such each language bundle can be easily
identified and updated.
Similarly if you used JDeveloper to create your own applications as
extensions to Fusion Applications you would use the native support for
resource bundles, and add them into the faces-config.xml file for
inclusion in your application. An example is this ADF customization video from our YouTube channel.
JDeveloper also supports automatic synchronization between your
underlying resource bundles and any translatable strings you add – very
handy. For more information see chapters on “Using Automatic Resource
Bundle Integration in JDeveloper” and “Manually Defining Resource
Bundles and Locales” in the Oracle Fusion Middleware Web User Interface Developer’s Guide for Oracle Application Development Framework.
FND Messages and Look-ups
FND Messages, as defined here, are not used for UI labels (they are
known as ‘strings’), but are the responses back to users as a result of
an action, such as from a page submit. Each ‘message’ is defined and
stored in the related database table (FND_MESSAGES_B), with another
(FND_MESSAGES_TL) holding any language-specific values. These come
seeded with the additional language installs, however if you customize
the messages via the “Manage Messages” task in Functional Setup Manager,
or add new ones, then currently (in Release 7) you’ll need to repeat it
for each language.
Figure 3 – An FND Message defined in an English user session.
Similarly Look-ups are stored in a translation table
(FND_LOOKUP_VALUES_TL) where appropriate, and can be customized by
setting the users session language and making the change in the Setup
and Maintenance task entitled “Manage [Standard|Common] Look-ups”.
Online Help
Yes, in fact all the seeded help is applied as part of each language pack install as part of the post-install provisioning process.
If you are editing or adding custom online help then the Create Help
screen provides a drop-down of which language your help customization
will apply to. This is shown in the video below from our YouTube channel, and obviously you’ll need to it for each language in use.
What is Coming for Translations?
Currently planned for Release 8 is something called the User Interface (UI) Text Editor.
This tool will allow the editing of all the text shown on the pages and
forms of Fusion Application. This will provide a search based on a
particular term or word, say “Worker”, and will allow it to be adjusted,
say to “Employee”, which then updates all the Resource Bundles that
contain it. In the case of multi-language environments, it will use the
users session language (locale) to know which Resource Bundles to apply
the change to.
This capability will also support customization sandboxes,
to help ensure changes can be tested and approved. It is also
interesting to note that the design currently allows any page-specific
customizations done using Page Composer or Application Composer to
over-write the global changes done via the UI Text Editor, allowing for
special context-sensitive values to still be used.
Further Reading and Resources
The following short list provides the mains resources for digging
into more detail on translation support for both Composer and JDeveloper
customization projects.
There is a dedicated chapter entitled “Translating Custom Text” in the Fusion Applications Extensibility Guide. This has good examples and steps for many tasks, especially administering resource bundles.
Using localization formatting (numbers, dates etc) for design-time changes is well documented in the Fusion Applications Developer Guide.
For more guidelines on general design-time globalization, see either
the ‘Internationalizing and Localizing Pages’ chapter in the Oracle
Fusion Middleware Web User Interface Developer’s Guide for Oracle
Application Development Framework (Oracle Fusion Applications Edition) or the general Oracle Database Globalization Support Guide.
The Oracle Architecture ‘A-Team’ provided a recent post
on customizing the user session timeout popup, using design-time
changes to resource bundles. It has detailed step-by-step examples which
can be a useful illustration.
