14 Creating Multi-Lingual Content
This chapter describes how to use the APIs provided with Oracle Portal to create content in different languages. It contains the following sections:
For more information about any of these APIs, refer to the Oracle Portal PL/SQL API Reference on Portal Center:
http://portalcenter.oracle.com
In the Portal Focus Areas section, click Portlet Development, then in the APIs and References section, click PL/SQL API Reference.
Tip:
Remember, if you are calling the APIs from a Web provider or external application, you need to set the session context first. For more information, refer to Section 10.1, "Setting the Session Context".14.1 Introduction to Multi-Lingual Support
The page group administrator must have configured the page group to support multiple languages before you can use the APIs to create translations of portal objects. Before using the APIs, it is recommended that you read Chapter 20 "Translating Portal Content" of the Oracle Fusion Middleware User's Guide for Oracle Portal to understand how to configure a page group and how objects with translations behave.
The basic approach to creating or modifying a translation of a portal object is to set the language context and then use the appropriate content management API to create or modify the item.
14.2 Querying the Default Language
To determine the default language of a page group, run the following query:
select distinct wwnls_api.get_language(default_language) "Page Group Default Language" from wwsbr_all_content_areas pg where name = 'MyPageGroup';
To determine the language context of a SQL*Plus session:
-
The SQL statement which is used to get the default language should be executed as Portal schema user. To connect to the protal schema, enter the portal schema password and the
SERVICE_NAME/SIDof the database where the portal repository is installed. -
Run the following query:
select wwctx_api.get_nls_language "Session Context Language Code", wwnls_api.get_language(wwctx_api.get_nls_language) "Language Description" from dual;
Note:
When you log in to SQL*Plus and set your user context, you are initially in the language specified by your NLS_LANG environment variable.14.3 Setting the Session Language
Before creating content in a different language, use the wwctx_api.set_nls_language API to set the session language, as shown in Example 14-1.
Example 14-1 Setting the Session Language (set_nls_language API)
begin
wwctx_api.set_nls_language(
p_nls_language => wwnls_api.GREEK,
p_nls_territory => wwnls_api.TER_GREECE
);
exception
...
end;
/
-
p_nls_language is the Globalization Support language abbreviation of the language that you want to set for the session.
-
p_nls_territory is the Globalization Support territory abbreviation of the territory that you want to set for the session.
For a list of available language and territory constants, refer to the documentation for the WWNLS_API package in the Oracle Portal PL/SQL API Reference on Portal Center:
http://portalcenter.oracle.com
In the Portal Focus Areas section, click Portlet Development, then in the APIs and References section, click PL/SQL API Reference.
14.4 Modifying an Existing Translation
Modifying an existing translation is simply a matter of setting the language context and using the appropriate API to modify the object. Example 14-2 modifies the text of an existing text item that has a translation in French.
Example 14-2 Modifying a Translation
declare
l_item_master_id number;
begin
-- Set the language context.
wwctx_api.set_nls_language(
p_nls_language => wwnls_api.FRENCH
);
-- Edit the item (this edits the French translation).
l_item_master_id := wwsbr_api.modify_item(
p_master_item_id => 453,
p_item_id => 454,
p_caid => 33,
p_folder_id => 45,
p_display_name => 'Revue de Film');
p_text => 'C'est le texte de la revue');
);
-- Process cache invalidation messages.
wwpro_api_invalidation.execute_cache_invalidation;
exception
...
end;
/
For information about the modify_item API used in Example 14-2, refer to Section 11.2.2, "Editing an Item".
14.5 Creating a Translation for an Item
If the session is using a different language from the default language for the page group and translations for the session language are enabled for the page group, the add_item API creates a translation for an item when the item is created. For example, if the default language for the page group is English, the session language is French, and French translations are enabled for the page group, the API adds the following two rows to the item table:
-
One with a value of 'us' (English) for the default language.
-
One with a value of 'f' (French) for the session language.
Other than the language, both rows will have identical values for all attributes, including the item ID. To avoid this, it is recommended that you always add an item in the default language first before creating any of its translations.
In similar circumstances, the modify_item API updates the translation for the session language (if it exists). If the translation does not exist, as long as translations are enabled for the session language, the API creates a new translation. Therefore, if you want to add a translation for an existing item, use the modify_item (or modify_item_post_upload) API. Example 14-3 creates a file item then changes the language context and adds a translation for the item.
Example 14-3 Creating a Translation
declare
l_item_masterthing_id number;
l_item_masterthing_id2 number;
l_item_id number;
begin
-- Set the language context.
wwctx_api.set_nls_language(
p_nls_language => wwnls_api.AMERICAN
);
-- Add an item that resides on the same server as the portal content repository
-- database.
l_item_masterthing_id := wwsbr_api.add_item(
p_caid => 53, - A known page group ID.
p_folder_id => 1, - A known page ID.
p_display_name => 'My File',
p_type_id => wwsbr_api.ITEM_TYPE_FILE,
p_type_caid => wwsbr_api.SHARED_OBJECTS,
p_region_id => 513, - A known region on the page.
p_description => 'Description of my file',
p_file_filename => '/docs_for_upload/English_File.txt'
);
-- Note that if the default language was not American then OracleAS Portal
-- would in addition automatically create a translation of the item in the
-- default language.
--
-- Determine the item id.
select id
into l_item_id
from wwsbr_all_items
where masterid = l_item_masterthing_id
and caid = l_site_id
and language = wwctx_api.get_nls_language
and is_current_version = 1;
-- Change the language context to French.
wwctx_api.set_nls_language(
p_nls_language => wwnls_api.FRENCH
);
-- Modify item adding its translation and any translated attributes.
l_item_masterthing_id2 := wwsbr_api.modify_item(
p_master_item_id => l_item_masterthing_id,
p_item_id => l_item_id,
p_caid => l_site_id,
p_folder_id => l_page_id,
p_display_name => 'Mon Fichier',
p_description => 'Description du fichier',
p_file_filename => '/docs_for_upload/French_File.txt'
);
-- Process cache invalidation messages.
wwpro_api_invalidation.execute_cache_invalidation;
exception
...
end;
/
For information about the add_item API used in Example 14-3, refer to Section 12.4, "Creating Items". For information about the modify_item API, refer to Section 11.2.2, "Editing an Item".
14.6 Translations and Item Versioning
If you attempt to create a new version of an item in a nondefault language, by setting p_addnewversion to TRUE using modify_item API, a new version is not created; a new translation is added instead.
When using versioning in conjunction with translations, we recommend that you create new versions of items in the default language and then translate the new version of the item.
For a more detailed discussion of the effect of item versioning on translations, refer to Section 20.3 "Creating Translatable Content" in the Oracle Fusion Middleware User's Guide for Oracle Portal.