Skip Headers

Oracle® Application Server Portal Developer's Guide 10g Release 3 (10.1.3) B25601-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 14 Creating Multi-Lingual Content

This chapter describes how to use the APIs provided with OracleAS Portal to create content in different languages. It contains the following sections:

- Introduction to Multi-Lingual Support

- Querying the Default Language

- Setting the Session Language

- Modifying an Existing Translation

- Creating a Translation for an Item

- Translations and Item Versioning

For more information about any of these APIs, refer to 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.

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

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.

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

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