14 Creating Multi-Lingual Content

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 Application Server Portal User's Guide 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, 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;

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.

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 Application Server 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.

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

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.1, "Creating File 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, 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 Application Server Portal User's Guide.