How do I translate my portal content?

An OracleAS Portal 10g Technical Note
February 2004

| Introduction | Overview | Creating and Editing Translations | Tracking Translations| Querying the Repository | More Information |

Introduction

This technical note describes the use of the Translations feature in OracleAS Portal 10g. This note is intended as a supplement to the OracleAS Portal 10g User's Guide.

Back to Top

Overview of the Translations Feature

OracleAS Portal allows you to store, manage, and publish translations of your Portal content. Many of the objects that are managed in your portal can be associated with one or more languages in addition to the default language defined for a page group. Translated content is automatically published to viewers of your portal in their selected language.

Although the translation feature is very useful and powerful, it is important to understand how translations are created, managed, published, and queried. In particular, the implicit creation of translations when an object is created or edited in a non-default language can cause confusion for your content contributors and portal users. For example:

1. When edits are unintentionally made to an object in a different language, the edits may appear to be lost when the object is viewed in the original, intended language. Users may not realize that multiple language records can exist for a single object.
2. When a non-translatable attribute is edited, the value of the attribute is automatically copied to all language records. The content contributor may wonder why the attribute value has suddenly changed when he switches to a different language.
3. Similarly, editing a translatable attribute does not copy the change to all language records. In this case, the content contributor may be concerned that his changes were lost when he views the object in a different language.
4. Translations may exist for one version of an item, but not for another version. If the current version changes, it may seem as if the translation has been lost.
   

What can be translated?

When we say that a translation exists for a content object in the portal repository (an item, page, item type, etc.), we mean that a specific instance of that object exists for a non-default language, in addition to the instance of the object that exists for the containing page group's default language. Translated values are stored for any translatable attribute in the object (the concept of a translatable attribute is explained later in this note). The following table shows, by object, the content attributes that can be translated:

In addition, facilities are provided through the Portal Development Kit (PDK) for portlet developers to manage the storage and retrieval of strings in different languages. See the PDK article Implementing NLS Service.

What is the default language?

Every page group has a default language. The default language for a page group is assigned from the list of installed languages when the page group is created, and cannot be changed.

Every object in a page group will have a record associated with the default language. In addition, if translations are enabled in the page group, each object may have a record associated with each of the available languages. These records are referred to as "translations" of the object.

How is the translation feature enabled?

Translations can be enabled in a page group for any installed language. Languages are installed by the Portal Administrator by using the OracleAS Portal Configuration Assistant (OPCA). Please refer to the LANGUAGE OPCA Mode documentation in the OracleAS Portal Configuration Guide.

To enable translations for an installed language in a page group, please refer to the the OracleAS Portal User's Guide.

How is the session language selected?

You can choose your session language on the OracleAS Portal Login Page, or by using the Set Language portlet. The portlet may already have been added to a page on the portal site, or you can add it to any page on which you have content management or customization privileges.

Note that the Set Language portlet displays all languages that are available in the portal, not just the languages that are available in the current page group.

When are translations displayed?

If a translation of an object exists for a particular language, the translation is automatically displayed when the language is selected for a user session in the Set Language portlet.

The rules for displaying translations are as follows:

1. If the default language is selected for the user session, then no translations are displayed.
2. If a non-default language is selected, and a translation of an object exists for that language, then the translation is displayed.
3. If a non-default language is selected, and no translation exists for an object, the default language instance of the object is displayed.

These rules are illustrated by the following table:

The same rules are applied to searches using the built-in Portal Search - only records that are valid for the current session language are displayed in search results. In the current release (10g (9.0.4)), UltraSearch cannot be used to search translated content.

Back to Top

Creating and Editing Translations

How are translations created?

A translation is implicitly created when an object is created or edited in a non-default language.

To create a translation for an existing object, perform the following steps:

1. Select the session language using the Set Language portlet.
2. Locate the object that you want to translate.
3. Edit the object. If the session language is enabled and is not the default language for the current page group, and a translation does not already exist for the object, then a translation is automatically created. If the session language is not enabled, then your edit will affect the default language instance of the object, and no translation is created. If the session language is enabled, and a translation already exists, then your edit will affect the translation.

When a translation is first created, the current attribute values for the default language are applied to the translation. From that point on, the attribute values for the translation can be changed only by editing the object while the session is set to use the translation language. Changing the default language attribute value will not affect existing translations (except for non-translatable attributes, as described later).

For example, a page is created in the default language English (us), with the following attributes (translatable attributes are marked with an *):

The page designer then switches to French and edits the page, changing the display name to Page De Voyage. Now, two records will exist for the page in the content repository (in this and all subsequent examples, records that are implicitly created have a yellow background):

Note that the value of the Keywords attribute for the French translation has defaulted to the value of the English version. If the page designer switches back to English and edits the value of the Keywords attribute, the changes are not inherited by the translation; e.g.:

If an object is created while a non-default language is active, then both the translation and the default language version are created, with identical attribute values. For example, if the Travel Page was created while the session language was set to French, two records with identical values (except for Language) would be created in the content repository:

Translations and Item Versions

The implicit behavior of translation creation also applies when you use versioning for items.

When you create a new version of an item, a new record is added to the Portal repository. All versions of an item have the same Master ID attribute value, but each version is assigned a new ID attribute value. A Current Version attribute indicates which version is active:

Now, switch to French and edit the current version. A French record is implicitly created for Version 2. Note that no translation exists for Version 1, and that both the English and French records for Version 2 have the same ID:

With the language still set to French, create a new version (3). An English record is implicitly created for Version 3, with attribute values copied from the English record for Version 2:

Switch back to English, and create a new version (4).

Note that no translation is created for Version 4. Therefore, when version 4 is the current version no translation will be displayed. This may cause users to think that their translations have "disappeared". Translations for version 4 must be manually created by editing version 4 in the non-default language(s).

Translations and Approvals

Translations of items can be submitted to an Approval Process when they are created or edited. However, the behavior can be confusing if the approver is using a different session language than the translation.

For example, a user with Manage Items With Approval privilege creates a French translation of an item. The translated display name of the item appears in the Approver's Notification Portlet, even when the Approver's session language is set to English:

However, if the Approver does not switch language to French, she will only be able to preview the item in English. For example, when she views the item in Preview Mode, she will see the following:

Similarly, when she clicks the item link to view the content (e.g. if the item is a file or text item), she will be seeing the English content, not the translated French content.

Therefore, to properly preview and approve content for a pending translation, Approvers must always set their session language to the same language as the translation.

Translatable vs. Non-Translatable Attributes

Not all attributes are translatable. When the value of a non-translatable attribute is modified, the change is copied to all language records for the current object (or version of the object).

For example, an item has the following attributes:

Display Name is translatable, and Publish Date is not translatable. When Publish Date is modified in any of the language records, the change is implicitly copied to all language records:

See the Overview (above) for the list of supplied attributes that are translatable. All other supplied attributes are not translatable.

When you create a custom attribute, you can specify if it is translatable or not. In general, dynamic attributes (such as PL/SQL attributes) or attributes that use a List of Values (LOV) should be made non-translatable if you don't want different values for the different languages.

Note that some objects, like categories and perspectives, can themselves have translatable properties which affect the way they are viewed, but when these objects are associated with an item or page the associated value is not translatable. For example, a category is internally named "CONFIDENTIAL". The internal name uniquely identifies the category and is not translatable, meaning that all translations of the category have the same name. Typically, only Page Group administrators will see or know the internal name. Display Name is a translatable property for category, and therefore the English and French records can have different display names. The English display name of the category is "Confidential Document", and the French display name is "Document Confidentiel".

An item is created in English. In the category list in the Add Item wizard, the category "CONFIDENTIAL" appears as "Confidential Document", as the display name is used in the selection list. The item is then edited in French (thereby creating a French translation). In the category list in the Edit Item wizard, the category will display as "Document Confidential", using the French display name.

If the category is changed in the French record to another value (e.g. "RESTRICTED"), the new category value will also be applied to the item's English record, because category is a non-translatable attribute for items. When the attribute is viewed, the appropriate category display name is used - in French it will appear as "Accès Restreint", in English it will appear as "Restricted Access", but the underlying category value ("RESTRICTED") will be the same in the two records.

Using the Content APIs

OracleAS Portal provides an API package called WWSBR_API for creating and editing content. For translations, these APIs mimic the behavior of the browser user interface - translations are created or edited implicitly, based on the setting of the session language.

For example, the function WWSBR_API.MODIFY_ITEM is called from a browser session, where the session is using a different language than the default language for the page group and translations for the session language are enabled for the page group. In this case, the API will update the translation for that language, if it exists. If a translation for the item does not exist, a new translation is created with the values passed to the function.

To create translations from an external environment such as SQL*Plus or a Java Portlet, you must set the session language using the procecure WWCTX_API.SET_NLS_LANGUAGE. The procedure is included with the 9.0.4 PDK. To use this procedure in version 9.0.2.6, patch 4489311 must be installed on your Portal server. Note that the WWSBR_API Documentation in the PL/SQL PDK was written before the availability of WWCTX_API.SET_NLS_LANGUAGE, and therefore states that it is not possible to set the session language in an external environment. This is no longer the case.

Deleting Translations

Currently, it is not possible to explicitly delete a translation.

For items, the following steps can be used to remove a translation:

1. Enable versioning on the page containing the item.
2. Create a new version of the item in the default language.
3. Delete the old version of the item using the Versions link in List View. All language records for the old version will be deleted.
   

Back to Top

Tracking Translations

Because translations are implicitly created, it may not be obvious what translations exist for an object. The following sections describe some techniques for keeping track of your translations.

Displaying the Translation Attribute

For items, a "Translations" attribute is available that can be displayed in an item region. Clicking this attribute will display a list of translations for the current version of the item.

To display the Translations attribute, edit the item region properties and add the attribute to the list of Displayed Attributes (see section 7.5.2.10 of the OracleAS Portal User's Guide - Changing the Attributes Displayed in a Region).

Custom Translation Reports

For all objects, you can track or report on the translations that exist by querying the content repository views. For example, the following query:

select name, language,display_name
from wwsbr_all_folders
where caid = 913
and id = 1

will display a list of translations that exist for the root page (WWSBR_ALL_FOLDERS.ID = 1) of the Page Group with ID 913 (WWSBR_ALL_FOLDERS.CAID = 913).

Please refer to the Content Repository View Documentation in the PL/SQL PDK.

Back to Top

Querying the Content Repository

OracleAS Portal provides a set of views for building custom queries against the content repository.

For most objects in the Portal repository, LANGUAGE forms part of the primary key. If you are using the translation feature for your content and do not specify the LANGUAGE column in your queries, you may get back multiple rows for an object.

For example, a Developer wants to produce a list of all the items on the root page of a page group. Translations are enabled on the page group, and the Developer wants to make sure that the list only contains items for the current session language of any user who will run the query. For items that are not translated, the item record for the page group's default language must be substituted when the current session is using a non-default language.

Therefore, a special subquery (italicized) is used to select the correct language record:

select i.display_name title, i.id latestversion
from wwsbr_all_items i
where i.folder_id = 1 and i.caid = 75 
and   i.active = 1 and i.is_current_version = 1
and (i.language = wwctx_api.get_nls_language -- the current session language
        or (  exists -- a row for the item in the page group default language
	          (select pg.id
               from wwsbr_all_content_areas pg
               where pg.id = i.caid
               and pg.default_language = i.language)
             and not exists -- a row for the item in the current language
              (select i2.id
               from wwsbr_all_items i2
               where i2.id = i.id
               and i2.language = wwctx_api.get_nls_language 
               and i2.active = i.active 
               and i2.is_current_version = i.is_current_version)
           )
     )

Note that the function wwctx_api.get_nls_language is used to get the current language setting. The example shows this function embedded in the query. This is done to simplify the example, and is also necessary if you are testing the query directly in an environment like SQL*Plus. Normally, it would be more efficient to assign the value returned by the function to a bind variable, and to use the bind variable in the query; e.g.

declare
   l_current_language  VARCHAR2(3) := wwctx_api.get_nls_language;
begin
    ...
	select ...
	from   wwsbr_all_items i
	where  ...
	and     (i.language = l_current_language ...
    ...
end;

Please refer to the Content Repository View Documentation in the PL/SQL PDK for more information and examples.

Back to Top

More Information

For more information on this and related topics, please refer to the following:

• Web Publishing and Content Management Page on OracleAS Portal Center (http://portalcenter.oracle.com/publishing)
• OracleAS Portal Content Repository View Documentation
• OracleAS Portal Content API Documentation
• OracleAS Portal User's Guide: HTML | PDF
• OracleAS Portal Configuration Guide HTML | PDF

Back to Top