| Oracle® HTML DB User's Guide Release 1.5 Part Number B10992-01 |
|
|
View PDF |
| Oracle® HTML DB User's Guide Release 1.5 Part Number B10992-01 |
|
|
View PDF |
This section describes how to translate an application built in Oracle HTML DB.
This section contains the following topics:
In Oracle HTML DB you can develop applications that can run concurrently in different languages. A single Oracle database instance and Oracle HTML DB can support multiple database sessions customized to support different language.
In general, translating an Oracle HTML DB application involves the following steps:
Map primary and target application IDs
Seed and export text to a file for translation
Translate the text in the file
Apply and publish the translated file
After you create an application, you specify a language preference on the Edit Application Attributes page. Under Globalization, you select a primary application language and select how the HTML DB engine determines the application language. You can specify to have the application language based on the user's browser language preference, an application preference, or an item preference.
Once Oracle HTML DB determines the language for an application, the HTML DB engine alters the database language for a specific page request. It then looks for a translated application in the appropriate language. If the HTML DB engine finds that language, it render the application using that definition. Otherwise, it renders the application in the base (or primary) application language.
Note that the text that displays within an application is not translated on the fly. Oracle HTML DB dynamically collects page attributes from either a base language application definition or an alternative application definition.
When you build an application in Oracle HTML DB, you define a large number of declarative attributes such as field labels, region headings, page header text, and so on. Using the steps described in this chapter, you can make all the application definition attributes within your application translatable.
If your application includes PL/SQL regions or PL/SQL processes, you may need to translate any generated HTML or text. Within Oracle HTML DB this type of generated HTML and text are called "messages." You can define all messages and translate them on the Translatable Messages page. You can use the HTMLDB_LANG.MESSAGE API to translate text strings from PL/SQL stored procedures, functions, triggers, packaged procedures and functions.
Dynamic translations are used for database data that needs to be translated at runtime. For example, you might use a dynamic translation to translate a list of values based on a database query. A dynamic translation consists of a "translate-from" language string, a language code, and a "translate-to" string. You can also use the HTMLDB_LANG.LANG API to retrieve dynamic translations programmatically.
By default, templates in Oracle HTML DB are not translatable and therefore not included in the generated translation file. Generally, templates do not and should not contain translatable text. However, if you need to mark a template as translatable, mark the Translatable check box on the Edit Page Template page.
To identify a template as translatable:
Click the Build icon.
Select the Templates tab.
Locate the template you wish to edit and click the edit icon.
Under Template Identification, select Translatable.
One way to include translatable text at the application level is to define the translatable text using static substitution strings. Since application level attributes are translated any text defined as a static substitution strings will be included in the generated translation file.
Globalization attributes specify how the HTML DB engine determines the primary language of an application.
To edit Globalization attributes:
Click the Build icon.
From the Available Applications list, select an application and click Go.
Select the Edit Attributes icon.
The Edit Application Attributes page appears.
Scroll down to Globalization.
From Application Primary Language, select the language in which the application is being developed.
From Application Language Derived From, specify how the HTML DB engine determines (or derives) the application language. Available options are described in Table 16-1.
Table 16-1 Application Language Derived From Options
| Option | Description |
|---|---|
| No NLS (Application not translated) | Select this option if the application will not be translated. |
| Use Application Primary Language | Determines the application primary language based on the Application Primary Language attribute (see step 5). |
| Browser (use browser language preference) | Determines the application primary language based on the user's browser language preference. |
| Application Preference (use FSP_LANGUAGE_PREFERENCE) | Determines the application primary language based a value defined using the HTMLDB_UTIL.SET_PREFERENCE API. Select this option to maintain the selected language preference across multiple log ins.
See Also: "SET_PREFERENCE Procedure" |
| Item Preference (use item containing preference) | Determines based on an application level item called FSP_LANGUAGE_PREFERENCE. Using this option requires Oracle HTML DB to determine the appropriate language preference every time the user logs in. |
|
See Also: |
The HTML DB engine applies Globalization settings for each rendered page. This default behavior can impact the display of certain items such as numbers and dates.
For example, suppose your application determines the application language based on the user's browser language preference. If the HTML DB engine determines the users's browser language preference is French, it displays dates and numbers in a format that conforms to French standards. You can override this default behavior and explicitly control how items display by applying a format mask. You apply a format mask by making a selection from the Display As list:
When you create the item
After you create the item by editing the item attributes
To edit item attributes
Click the Build icon.
From the Available Applications list, select an application and click Go.
Navigate to the appropriate page.
Under Items, drill down on the item name.
The Edit Page Item page appears.
Under Identification, make a select from the Display As list.
If your application needs to run in several languages (such as Chinese or Japanese) simultaneously, you should consider configuring your database with a character set to support all of the languages. The same character set has to be configured in the corresponding DAD (Data Access Description) in mod_plsql. UTF8 and AL32UTF8 are the character sets you can use to support almost all languages around the world.
To translate an application developed in Oracle HTML DB, you must map the primary and target application IDs, seed and export text to a translation file, translate the text, and then apply and publish the translation file.
Topics in this section include:
You perform the translation process on the Translate Application page.
To navigate to the Translate Application page:
Click the Build icon.
From the Available Applications list, select an application and click Go.
Select the Utilities tab.
Click Translate Application.
The Translate Application page appears.
The first step in translating an application is to map the primary and target application IDs. The primary application is the application to be translated. The target application is the resulting translated application.
To map the primary and target application IDs:
Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)
On the Translate Application page, select Map your primary language application to a translated application ID.
The Application Mappings page appears.
Click Create.
On the Translation Application Mapping page:
In Translation Application, type a numeric application ID to identify the target application.
From Translation Application Language Code, select the language you are translating to.
In Image Directory, enter the directory where images will be obtained.
This attribute determines the virtual directory for translated images. For example, if your primary language application had an image prefix of '/images/', you could define additional virtual directories for other languages such as '/images/de/' for German or '/images/es/' for Spanish.
Click Create.
The second step in translating an application is to seed the translation table and then export the translation text to a translation file.
Seeding translatable text copies all strings that may require translation to an Oracle HTML DB database table that contains that contains the original language version and the possibility of storing the translated version.
To seed translatable text:
Navigate to the Translate Application page. (See "Navigating to the Translate Application Page" .)
On the Translate Application page, select Seed and export the translation text of your application into a translation file.
From Language Mapping, select the appropriate primary and target application ID map.
Click Seed Translatable Text.
The XLIFF Export page appears.
|
Note: XML Localization Interchange File Format (XLIFF) is a XML-based format for exchanging localization data. For more information on the XLIFF, or to view the XLIFF specification see:http://www.xliff.org |
Once you have seeded translatable text, a status box displays at the top of the XLIFF Export page indicating the total number of attributes that may require translation as well as the number of:
Existing updated attributes that may require translation
New attributes that may require translation
Purged attributes that no longer require translation
You can use this information to determine whether you need to export translatable text for an entire application or just a specific page.
The XLIFF Export page is divided into two sections. Use the upper half of the page to export translatable text for an entire application (that is, all pages, lists of values, messages, and so on). Use the lower section to export translatable text for a specific page.
To export translatable text for an entire application:
Seed the translatable text as described in the previous procedure, "Seeding Translatable Text".
Under Step 2, Export XLIFF:
From Application, select the appropriate primary and target application ID map
Specify whether to include XLIFF target elements
Under Export, specify what translation text is included in your XLIFF file
Click Export XLIFF for Application
Follow the on-screen instructions.
To export translatable text for a specific page:
Seed translatable text as described in "Seeding Translatable Text".
Under Export XLIFF for specific Page:
From Application, select the appropriate primary and target application ID map
Specify whether to include XLIFF target elements
Under Export, specify what translation text is included in your XLIFF file
Click Export XLIFF for Page
Follow the on-screen instructions.
When Oracle HTML DB generates an XLIFF document, each document contains multiple translation units. Each translation unit consists of a source element and a target element. If you have not previously translated an application, you must include source and target elements. However, if you have a previous translation, you have the option of disabling this option and only generating a file containing source elements.
After you export a translatable file to XLIFF format, you can translate it into the appropriate languages. Since XLIFF is an open standard XML file for exchanging translation, most translation vendors should support it. Oracle HTML DB only supports XLIFF files encoded in UTF-8 character sets. In other words, it exports XLIFF files for translation in UTF-8 and assumes that the translated XLIFF files will be in the same character set.
Translation is a time consuming task. Oracle HTML DB supports incremental translation so that application development can be done in parallel with the translation. An XLIFF file can be translated and uploaded to Oracle HTML DB even when only part of the XLIFF file is translated. For strings that have no translation in the corresponding translated application, Oracle HTML DB uses the corresponding ones in the primary language.
|
See Also: For more information on the XLIFF, or to view the XLIFF specification see:http://www.xliff.org |
Once your XLIFF document has been translated, the next step is to upload it back into Oracle HTML DB.
To upload a translated XLIFF document:
Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)
On the Translate Application page, select Apply your translation file and publish.
Click Upload XLIFF.
On the XLIFF Upload page:
Specify a title
Enter a description
Click Browse and locate the file to be uploaded
Click Upload XLIFF File
The uploaded document appears in the XLIFF Files repository.
Once you upload an XLIFF document, the next step is to apply the XLIFF document and then publish the translated application. When you apply an XLIFF document, the HTML DB engine parses the file and then updates the translation tables with the new translatable text.
Publishing your application creates a copy of the base language application, substituting the translated text strings from your translations table. This published application can then be used to render your application in alternate languages.
Remember that in order to run an application in an alternative language, you need to run it with Globalization settings that will cause an alternative language version to display. For example, if the language is derived from the browser language, you must set the browser language to the same language as the translated application.
To apply and publish a translated XLIFF document:
Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)
On the Translate Application page, select Apply your translation file and publish.
In the XLIFF Files repository, click the view icon.
From Apply to, select the appropriate primary and target application ID map.
Click Apply XLIFF Translation File.
Click Publish Application.
To delete an uploaded XLIFF document:
Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)
On the Translate Application page, select Apply your translation file and publish.
In the XLIFF Files repository, select the check box to the left of the document title.
Click Delete Checked.
You should verify the existence of the translated application once it is published. Translated applications do not display in the Available Applications list on the Application Builder home page. Instead, use the Application Navigation pane on the left side of the page.
Note that in order for a translated application to appear in Application Builder, you need to make sure the you have correctly configured the application Globalization attributes.
If your application includes PL/SQL regions or PL/SQL processes or calls PL/SQL package, procedures, or functions, you may need to translate generated HTML. First, you define each message on the Translatable Messages page. Second, you use the HTMLDB_LANG.MESSAGE API to translate the messages from PL/SQL stored procedures, functions, triggers, or packaged procedures and functions.
You create translatable messages on the Translate Messages page.
To define a new translation message:
Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)
On the Translate Application page, select Optionally translate messages which are used by PL/SQL procedures and functions.
On the Translate Messages page, click Create.
On the Identify Text Message page:
In Name, type a name to identify the text message
In Language, select the language for which the message would be used
In text, type the text to be returned when the text message is called.
For example, you could define the message GREETING_MSG in English as:
Good morning %0
Or, you could define the message GREETING_MSG in German as:
Guten Tag %0
Click Create.
Use the HTMLDB_LANG.MESSAGE API to translate text strings (or messages) generated from PL/SQL stored procedures, functions, triggers, packaged procedures and functions.
HTMLDB_LANG.MESSAGE (
p_name IN VARCHAR2 DEFAULT NULL,
p0 IN VARCHAR2 DEFAULT NULL,
p1 IN VARCHAR2 DEFAULT NULL,
p2 IN VARCHAR2 DEFAULT NULL,
...
p9 IN VARCHAR2 DEFAULT NULL,
p_lang IN VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;
Table 16-2 describes the parameters available in the HTMLDB_LANG.MESSAGE.
Table 16-2 HTMLDB_LANG.MESSAGE Parameters
| Parameter | Description |
|---|---|
p_name |
Name of the message as defined in Oracle HTML DB. |
p0
...
|
Dynamic substitution value. p0 corresponds to 0% in the message. p1 corresponds to 1% in the message. p2 corresponds to2% in the message and so on. |
p_lang |
Language code for the message to be retrieved. If not specified, Oracle HTML DB uses the current language for the user as defined in the Application Language Derived From attribute.
See Also: "Specifying the Primary Language for an Application " |
The following example assumes you have defined a message called GREETING_MSG in your application in English as Good morning%0 and in German as Guten Tag%1. The following example demonstrates how you could invoke this message from PL/SQL:
BEGIN
--
-- Print the greeting
--
HTMLDB_LANG.MESSAGE('GREETING_MSG', v('APP_USER'));
END;
How p_lang attribute is defined depends on how the HTML DB engine derives the Application Primary Language. For example, if you are running the application in German and the previous call is made HTMLDB_LANG.MESSAGE, the HTML DB engine first looks for a message called GREETING_MSG with a LANG_CODE of de. If it does not find anything, then it will revert to the Application Primary Language attribute. If it still does not find anything, the HTML DB engine looks for a message by this name with a language code of en-us.
|
See Also: "Specifying the Primary Language for an Application " for more information on the Application Primary Language attribute. |
You create a dynamic translation to translate dynamic pieces of data. For example, you might use a dynamic translation on a list of values based on a database query.
Dynamic translations differ from messages in that you query a specific string rather then a message name. You define dynamic translations on the Dynamic Translations page. You then use the HTMLDB_LANG.LANG API to return the dynamic translation string identified by the parameter p_primary_text_string.
You define dynamic translations on the Dynamic Translations page. A dynamic translation consists of a "translate-from" language string, a language code, and a "translate-to" string.
To define a dynamic translation:
Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)
On the Translate Application page, select Optionally identify any data that needs to be dynamically translated to support SQL based lists of values.
On the Dynamic Translations page, click Create and specify the following:
In Language, select a target language
In Translate From Text, type the source text to be translated
In Translate To, type the translated text
Click Create.
HTMLDB_LANG.LANG (
p_primary_text_string IN VARCHAR2 DEFAULT NULL,
p0 IN VARCHAR2 DEFAULT NULL,
p1 IN VARCHAR2 DEFAULT NULL,
p2 IN VARCHAR2 DEFAULT NULL,
...
p9 IN VARCHAR2 DEFAULT NULL,
p_primary_language IN VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;
Table 16-3 describes the parameters available in the HTMLDB_LANG.LANG.
Table 16-3 HTMLDB_LANG.LANG Parameters
| Parameter | Description |
|---|---|
p_primary_string |
Text string of the primary language. This will be the value of the Translate From Text in the dynamic translation. |
p0
...
|
Dynamic substitution value. p0 corresponds to 0% in the in the translation string. p1 corresponds to 1% in the in the translation string. p2 corresponds to 2% in the in the translation string and so on. |
p_primary_language |
Language code for the message to be retrieved. If not specified, Oracle HTML DB uses the current language for the user as defined in the Application Language Derived From attribute.
See Also: "Specifying the Primary Language for an Application " |
Suppose you have a table that defines all primary colors. You could define a dynamic message for each color and then apply the LANG function to the defined values in a query. For example:
SELECT HTMLDB_LANG.LANG(color) FROM my_colors
For example, suppose you were running the application in German andRED was a value for the color column in my_colors table. If you defined the German word for red, the previous example would return ROT.
If you are building a multilingual application, it is important to understand how Oracle HTML DB globalization codes impact the way in which your application runs. These codes are set automatically based on the application-level Globalization attributes you select.
NLS_LANGUAGE and NLS_TERRITORY determine the default presentation of number, dates, and currency.
Table 16-4 describes the globalization codes in Oracle HTML DB.
Table 16-4 Oracle HTML DB Globalization Codes
| Language Name | Language Code | NLS_LANGUAGE | NLS_TERRITORY |
|---|---|---|---|
| Arabic | ar |
ARABIC |
|
| Assamese | as |
ASSAMESE |
INDIA |
| Bengali | bn |
BANGLA |
|
| Bulgarian | bg |
BULGARIAN |
BULGARIA |
| Catalan | ca |
CATALAN |
CATALONIA |
| Chinese (China) | zh-cn |
SIMPLIFIED CHINESE |
CHINA |
| Chinese (Hong Kong SAR) | zh-hk |
TRADITIONAL CHINESE |
HONG KONG |
| Chinese (Singapore) | zh-sg |
SIMPLIFIED CHINESE |
SINGAPORE |
| Chinese (Taiwan) | zh-tw |
TRADITIONAL CHINESE |
TAIWAN |
| Chinese | zh |
SIMPLIFIED CHINESE |
CHINA |
| Croatian | hr |
CROATIAN |
CROATIA |
| Czech | cs |
CZECH |
CZECH REPUBLIC |
| Danish | da |
DANISH |
DENMARK |
| Dutch (Netherlands) | nl |
DUTCH |
THE NETHERLANDS |
| English (United States) | en-us |
AMERICAN |
AMERICA |
| English | en |
ENGLISH |
|
| Estonian | et |
ESTONIAN |
ESTONIA |
| Finnish | fi |
FINNISH |
FINLAND |
| French (Canada) | fr-ca |
CANADIAN FRENCH |
CANADA |
| French (France) | fr |
FRENCH |
FRANCE |
| German (Germany) | de |
GERMAN |
GERMANY |
| Greek | el |
GREEK |
GREECE |
| Gujarati | gu |
GUJARATI |
|
| Hebrew | he |
HEBREW |
ISRAEL |
| Hindi | hi |
HINDI |
INDIA |
| Hungarian | hu |
HUNGARIAN |
HUNGARY |
| Icelandic | is |
ICELANDIC |
ICELAND |
| Indonesian | id |
INDONESIAN |
INDONESIA |
| Italian (Italy) | it |
ITALIAN |
ITALY |
| Japanese | ja |
JAPANESE |
JAPAN |
| Kannada | kn |
KANNADA |
INDIA |
| Korean | ko |
KOREAN |
KOREA |
| Latvian | lv |
LATVIAN |
LATVIA |
| Lithuanian | lt |
LITHUANIAN |
LITHUANIANA |
| Malay (Malaysia) | ms |
MALAY |
MALAYSIA |
| Malayalam | ml |
MALAYALAM |
|
| Marathi | mr |
MARATHI |
|
| Norwegian | no |
NORWEGIAN |
NORWAY |
| Oriya | or |
ORIYA |
|
| Polish | pl |
POLISH |
POLAND |
| Portuguese (Brazil) | pt-br |
BRAZILIAN PORTUGUESE |
BRAZIL |
| Portuguese (Portugal) | pt |
PORTUGUESE |
PORTUGAL |
| Punjabi | pa |
PUNJABI |
|
| Romanian | ro |
ROMANIAN |
ROMANIA |
| Russian | ru |
RUSSIAN |
|
| Slovak | sk |
SLOVAK |
SLOVAKIA |
| Slovenian | sl |
SLOVENIAN |
SLOVENIA |
| Spanish | es |
SPANISH |
SPAIN |
| Spanish (Mexico) | es-mx |
MEXICAN SPANISH |
MEXICO |
| Swedish | sv |
SWEDISH |
SWEDEN |
| Tamil | ta |
TAMIL |
|
| Telugu | te |
TELUGU |
|
| Thai | th |
THAI |
THAILAND |
| Turkish | tr |
TURKISH |
TURKEY |
| Ukrainian | uk |
UKRAINIAN |
UKRAINE |
| Vietnamese | vi |
VIETNAMESE |
VIETNAM |
|
 Copyright © 2003 Oracle Corporation All Rights Reserved. |
|