25 Configuring Sites for Multilingual Support

How would you empower your site users to translate site pages? Configure multilingual support. You can also create site-specific delivery rules, rules that determine the language versions of assets to be shown on the online site, and also handle visitors’ requests for unavailable language versions.

When you configure a site for multilingual support, users in that site gain the ability to assign locale (language version) designations to assets, and to create translations of assets.

Topics:

25.1 About Configuring a Site for Multilingual Support

Are you looking for answers to questions such as these: what’s the best way to differentiate semantically identical assets and group locales, how you should use locales and dimension sets for cross-site multilingual support, what’s the best way to handle asset relationships and approval dependencies during editing and translation?

See these topics:

25.1.1 Dimensions

Locale designations in WebCenter Sites are implemented through the concept of dimensions. A dimension is an identifier that differentiates assets that are otherwise semantically identical. A locale (such as en_US for US English) is thus a type of dimension that differentiates two translations of the same content.

Dimensions are represented by assets of type Dimension. This asset type must be enabled by developers on a per-site basis so that users can create Dimension assets (of subtype Locale), and so that content providers can assign locale designations to assets they want to translate.

Note:

Users cannot create translations of assets that have no locale designation assigned.

Each Dimension asset represents a locale in the site. For example, an en_US Dimension asset represents US English, and an fr_CA Dimension asset represents Canadian French. When a content asset is assigned a locale, the assignment is recorded in the assetType_Dim table for the corresponding asset type.

Publishing content in a given locale requires enabling the locale on the online site, that is, publishing the Dimension asset representing the locale to the delivery system, and including the locale in the site's dimension set. See Dimension Sets.

25.1.2 Dimension Sets

When you have created your locales, we recommend that you create at least one dimension set. A dimension set is a grouping of dimension assets (locales), which affects the delivery of content to the site visitor in the following ways:

  • A dimension set defines which locales are designated as enabled for the online site. In other words, a dimension set determines the languages in which content will be shown to the visitors. For example, one dimension set would contain European languages, another Asian languages, and so on.

  • A dimension set defines how to filter content based on locale. For example, how to handle content that does not exist in the visitor's preferred language at the time the visitor requests it. If you do not publish a dimension set to the delivery system, locale filtering will not function. For information on locale filtering, see Working with Locale Filtering.

    Note:

    Dimension sets do not affect the operation of WebCenter Sites user interfaces.

For locale filtering to function on the online site, you must approve and publish to the delivery system both the DimensionSet assets and the Dimension assets referenced by each dimension set. (Because referenced Dimension assets are dependents of the DimensionSet assets referencing them, they must be approved with their respective DimensionSet assets.)

25.1.3 Cross-Site Multilingual Support

If you are setting up multilingual support in multiple sites, you can choose to implement one of the following scenarios:

  • Create the locales, but no dimension sets

    This option allows content providers to manage content in multiple languages, but does not enable render-time locale filtering. Use this option only if translations in all required languages will exist for each asset from the very beginning.

  • Create the locales and a dimension set, and share them across your sites

    This option provides the simplest way of enabling multilingual support on multiple sites. Sites set up in this way share the properties stored in the dimension set (locales enabled for display on the online site, the locale filtering method, and, if applicable, the fallback hierarchy (the path the Hierarchical filter traverses when looking up asset translations at render time). See The Hierarchical Filter. If you are creating a bare-bones site that you will replicate into multiple target sites, it is best to share your locales to the target sites.

  • Create separate locales and dimension sets for each site

    This option affords the most flexibility, at the cost of increased configuration complexity. Sites set up this way benefit from the fact that properties such as locale filter type or fallback hierarchy can be tailored to each site.

    Note:

    While creating duplicate Dimension assets to represent the same language in multiple sites is possible, it is not recommended, as it introduces unnecessary complexity.

  • A mixture of the latter two options

    This option provides the right balance between flexibility and configuration complexity. As a possible best practice, you would create a pool of unique locales, share the locales required by each site from that pool, and share or create dimension sets for each site as needed.

25.1.4 Master Assets, Translations, and Multilingual Sets

When an asset is assigned a locale for the first time, it gains master, or dimension parent, status. Master status allows the formation of a multilingual set (a group of assets whose content is semantically identical, but exists in different languages. (Note that this is not the same as a dimension set; a dimension set only affects the online site and the way assets are rendered.)

Note:

The terms master asset and dimension parent are equivalent. Master asset is displayed in WebCenter Sites's user interfaces; dimension parent is used in the Tag Reference for Oracle WebCenter Sites, database table names (such as assetType_DimP), and element code.

For example, when you designate an Article asset as US English (en_US), and create translations of it in whichever locales are enabled in the site (such as French (fr_CA) and German (de_DE)), the translations point to their dimension parent (the US English asset) to indicate they are semantically equivalent to the master and one another.

When you create a translation of an asset with master status, WebCenter Sites copies the asset and assigns the locale of your choice to the copy. You then enter the translated content and save the translation as a new asset.

At this point, the source asset and its translation are linked into a multilingual set, and the translation adopts the source asset as its master, or dimension parent. Any member of the set that is not the master can be given master status; however, only one set member at a time can be the master.

The linking is accomplished through the assetType_DimP table for the asset type. The table stores the following information:

  • ID of the master (dimension parent) asset

  • ID of the translation asset

  • ID of the locale dimension asset assigned to that translation

Even though WebCenter Sites interfaces allow you to initiate the creation of a translation from either the master asset or any of its existing translations, all translations in the multilingual set always point to the dimension parent (master) asset.

Note:

If a locale-aware asset is being revision-tracked, changes to asset locale data (such as locale designation or master status) do not generate a new version of the asset.

25.1.5 Translations and Asset Relationships

The way asset relationships are handled when an asset is translated is summarized in this table:

Table 25-1 Asset Relationships

Relationship Type Behavior

Associations

When an asset containing associations is translated, all assets associated with the source asset are automatically associated with the translation. You then have the choice to translate the associated assets and associate the translated versions with the translated parent asset.

Collections

When you create a translation of a Collection asset, the new Collection asset retains the member assets of the source asset. You then have the choice to translate the member assets and place the translated versions in the new Collection asset, replacing the member assets carried over from the old collection.

Static Lists Recommendations

When you create a new language version of a Static Lists recommendation, the new Recommendation asset retains the member assets of the source asset. You then have the choice to translate the member assets and place the translated versions in the new Recommendation asset, replacing the member assets carried over from the old collection.

Dynamic Lists Recommendations

Since Dynamic Lists recommendations are populated by element code, they are not affected.

Related Items Recommendations

When an asset containing Related Items associations is translated, all assets associated with the source asset are automatically associated with the translation. You then have the choice to translate the associated assets and associate the translated versions with the translated parent asset.

Asset-Type Attributes

When an asset containing associations through asset-type attributes is translated, all assets associated with the source asset are automatically associated with the translation. You then have the choice to translate the associated assets and associate the translated versions with the translated parent asset.

Embedded Links

Embedded links are not affected. When an asset containing embedded links is translated, you must manually update the links to point to the corresponding translations of the linked content (if such translations exist).

For information on handling asset relationships at render time, see Working with Locale Filtering.

25.1.6 Approval Dependencies

An approval dependency exists between two assets when editing one of the assets causes the other's approval status to change. This table summarizes the approval dependencies affecting localized assets:

Table 25-2 Approval Dependencies

Dependency Effect on Asset Approval

An Exists dependency exists between a localized asset and the Dimension asset representing the assigned locale.

To approve a localized asset for publishing, the corresponding Dimension asset must also be approved.

In a multilingual set, an Exists dependency exists between the master asset and each translation linked to it.

When you create the first translation of an asset, you must approve both the asset and its translation.

To approve a translation, you must also approve the corresponding master asset, unless the master asset has been approved.

You must reapprove all members of the set if:

  • You add a new translation to, or delete an existing translation from the set.

  • You edit the set's master asset.

  • You designate another member of the set as the master.

An Exists dependency exists between a DimensionSet asset and the Dimension assets representing the locales enabled in that dimension set.

To approve a dimension set, the corresponding Dimension assets must also be approved.

25.2 Working with Locale Filtering

On the online site, visitors may choose a language in which the assets of their interest have not yet been translated. You can use a locale filter that decides which translation should show on the site in the absence of the visitor’s preferred language and in the current circumstances.

For example, you could let the business logic decide what to do if a requested asset does not exist in the requested language.

By using locale filtering, you can also spread editorial work over time by allowing content providers to create the required translations after the original content is published to the online site. Locale filtering allows the site to automatically pick up the missing translations as soon as they are published to the delivery system.

Keep in mind that locale filtering introduces additional load on the delivery system. The amount of additional load depends on the complexity of the filtering logic.

This section includes the following topics:

25.2.1 Options for Implementing Asset Relationships Through Locale Filtering

The way you choose to implement locale filtering will have an influence on how asset relationships on your site are structured, and vice versa, depending on the way you want the online site to behave.

You can choose to implement one of the following options:

  • Maintain different asset relationship trees for each locale

    When rendering assets, this model renders whatever assets are associated with the requested asset.

    For example, if an asset exists in English and French, and each version has a unique set of associated assets, each version is rendered with its respective associated assets. Filtering is only used to look up and deliver a version of the requested asset matching the language preference specified by the visitor; the associated assets are expected to have been translated into all required languages.

    This model allows for completely independent content for each language. It is used in the First Site II sample site.

  • Use the same asset relationship tree for all locales

    When rendering assets, this model substitutes the associated assets of the requested asset with the assets associated with a specific language version of the requested asset, regardless of the language preference specified by the visitor.

    For example, if an asset exists in English and French, each version has a unique set of associated assets, and the visitor specified French as their language preference, filtering will look up and deliver the French version of the requested asset, but it will substitute the associated assets of the English version in place of those of the French version (assuming the language version from which filtering is to derive associations is English).

    This model ensures consistent content across all languages.

  • A mixture of the two models

    Allows for the greatest amount of flexibility and customization for your site. The optimal proportion between the two models will depend on the intended behavior of your site.

25.2.2 Understanding the Included Locale Filters

WebCenter Sites ships with the following locale filters:

You also have the option to implement custom locale filters, if desired. For information about custom filters, see About Using Custom Locale Filters.

Note that depending on the type of filter you choose to implement, the assets being filtered must satisfy one, or both of the following conditions:

  • Assets must have locale designations assigned. Assets without locale designations will be ignored by locale filters.

  • Assets that are translations of one another must be linked into multilingual sets (that is, designated as translations of one another through a master asset). Otherwise, the filters are not able to perform the necessary translation lookups.

25.2.2.1 The Simple Filter

The Simple filter is a possible choice for a site that should only be rendered in one language, but whose content exists in multiple languages. The filter checks the following:

  • Whether the requested asset is in the language specified by the visitor

  • Whether the locale of the asset is listed in the site's dimension set

If both conditions are met, the filter passes the asset to the template for rendering; otherwise, nothing is rendered.

The Simple filter has the least impact on delivery system performance, but increases the amount of editorial work that needs to be done, as assets must exist in the required language versions or they are not displayed on the online site.

25.2.2.2 The SimpleLookup Filter

The SimpleLookup filter is ideal for a site that should only be rendered in one language, but whose content may exist in multiple languages, and for which there is no guarantee that all of the necessary translations exist at render time. The filter checks the following:

  • Whether the requested asset is in the language specified by the visitor

  • Whether the locale of the asset is listed in the site's dimension set

If the requested asset is not in the visitor's preferred language, the filter looks up a suitable replacement by checking the asset's translations. If the filter finds a matching translation, it passes it to the template; otherwise, nothing is rendered. (The filter will also return nothing if the locale of the translation is not included in the site's dimension set.)

This filter offers a reasonable balance between performance and functionality. While the lookup queries slightly increase the load on the delivery system, the amount of editorial work done to create assets can be reduced, as the required translations can be created after the original content is published to the online site. The lookup mechanism will pick up the missing translations as soon as they are published to the delivery system.

25.2.2.3 The Hierarchical Filter

The Hierarchical filter checks whether the locale of the requested asset matches the locale requested by the visitor. If the locales do not match, the filter checks the asset's translations to see if a suitable replacement exists. If the filter finds a matching translation, it passes it to the template; otherwise, it substitutes translations of the requested asset according to the fallback hierarchy you set up when you configure the site's dimension set. The fallback hierarchy determines which language versions the filter should substitute for the requested asset, and in what order.

For example, consider the following hierarchy:

  • en_US (US English)

  • de_DE (German)

    • de_CH (Swiss German)

    • de_AT (Austrian German)

  • fr_FR (French)

    • fr_BE (Belgian French)

    • fr_CA (Canadian French)

  • en_UK (British English)

In our example, when the visitor requests an asset in Swiss German (de_CH), the filter looks up the asset's translations and if it finds a Swiss German version of the asset, it passes that version to the template. If the filter cannot find a Swiss German version, it falls back to the next best locale in the hierarchy path, German (de_DE). If, in turn, no German translation exists, the filter follows the path specified in the hierarchy until it reaches the top of the tree. If no match is found in the process, nothing is rendered.

Note that the above example describes a situation in which the visitor specifies a single preferred language. If the user specifies multiple preferred languages (in most cases, in the form of an ordered list), the filter attempts to find a match in the fallback hierarchy for the visitor's most preferred language. If no match is found, the filter checks the next language on the visitor's list, until a match in the fallback hierarchy is found. When that happens, the filter attempts to substitute translations of the requested asset by tracing a path from the matching locale to the top of the fallback tree, as described earlier.

For example, if the user's preferred languages are Japanese, French, and English (in that order), the filter attempts to locate Japanese in its fallback hierarchy. Since Japanese is not in the hierarchy, the filter then attempts to locate French. French is in the hierarchy, so the filter traces a path from French to the root node of the tree, and attempts substitution according to that path, as illustrated by the example earlier in this section.

While powerful and convenient, the hierarchical filter has the following drawbacks:

  • The additional database queries run by the filter tax the performance of the delivery system. To minimize the performance hit, editorial work should be done to ensure that content exist in as many of the required languages as possible, so that the filter's activity is minimized. (You may also choose to use a different filter.)

  • Control over which assets to display on the online site is put exclusively in the hands of the site developer or administrator. This is because the filter follows the fallback tree configured in the dimension set, rather than the preference order specified by the site visitor (assuming the site is set up to accept multiple language preferences from each visitor).

25.2.3 About Using Custom Locale Filters

Depending on the design of your site, you may decide to create custom filters. For example, your site design might call for a hierarchical (fallback) filter that favors the locale priority specified by the visitor, rather than the one defined in the dimension set. In such cases, a field in the Edit form for the DimensionSet asset lets you specify a custom filter class.

25.2.4 Accounting for Compositional Dependencies

If you decide to incorporate locale filtering on your site, you must account for the additional compositional dependencies that are introduced as a result. Compositional dependencies determine how pages are cached on your delivery system.

This section includes the following topics:

25.2.4.1 Asset Lookup Chain

When using locale filtering to look up a translation of an asset, the following factors determine how pages are cached, based on which assets are loaded during the lookup process:

  • The filtering logic employed

  • The page and asset from which the lookup request originates

  • The language preference specified by the visitor

A cached page containing the requested asset is dependent on all assets loaded during the lookup process. Thus, if an asset that is loaded during the lookup process is modified, the affected page is flushed from the cache.

For example, consider the SimpleLookup filter and the following multilingual set:

  • en_US (master)

  • fr_FR (translation)

  • de_DE (translation)

If a visitor requests a page containing the French version, but the visitor's language preference is German, the lookup chain is as follows:

fr_FR > en_US > de_DE

In this example, all three assets are loaded, because the filter must first load the master asset linked to the French version, and then use the master asset to look up the German version. Thus, if any of these three assets is modified, the affected page is flushed from the cache.

If, on the other hand, the user requested the US English version, which is the master asset of the set, then the lookup chain would be shorter:

fr_FR > en_US

In such case, the French and US English versions are loaded, but the German version is not. Thus, modifying the German version would not cause the corresponding page to be flushed from the cache, but modifying the French or US English versions would.

For a detailed explanation of the lookup mechanisms employed by locale filters included with WebCenter Sites, see Understanding the Included Locale Filters.

Caching Rules explains the caching rules applicable to multilingual assets.

25.2.4.2 Caching Rules

Once the translation lookup occurs and the affected page is cached, the page is flushed from the cache whenever one of the following occurs:

  • A new language is added to the multilingual set

  • A translation that was part of the lookup chain when the page was rendered is edited

  • A translation that is a member of the multilingual set is deleted

  • The set's master asset is edited

  • Another member of the set is designated as the master

25.2.5 About Adding Filtering Support to Your Site

To add support for locale filtering to your site, you must modify the templates and element code used on your site.

When the template code fetches an asset via the asset's c/cid values, the locale filter executes its business logic on the incoming c/cid values and returns the resulting c/cid values (or nothing) to the template for rendering.

The structure of your site will influence how you implement locale filtering in your templates, and vice versa. It will also determine the behavior of your site in different scenarios.

For example, imagine five articles, each existing in two languages, en (English), and fr (French). The articles would be a1en, a1fr, a2en, a2fr, and so on. We can decide to put these articles into a collection and implement locale filtering in one of the following ways:

  • Create an English collection, c1en, and assign all of the English articles to it. This way, before we render the collection, we would simply filter the c/cid of the c1en asset, then render its children without filtering their c/cid values, because we trust the c1en collection to be in a single language.

  • Create a multilingual collection (without assigning a locale to it) and add the articles in whatever languages are desired. Then, when rendering each article, filter the article c/cid values so that the article is rendered in the locale specified by the visitor.

The rest of this section provides code examples based on the FirstSiteII sample site. We recommend that you examine the FirstSiteII code to get an idea of how it multilingual support.

This section includes the following topics:

25.2.5.1 About Adding Filtering to Templates

Usually, you would place your filter code into a utility element and call the element at the top of the template to process the c/cid values.

The following example shows how the FSIILayout template calls the filter code stored in the FSIICommon/Multilingual/Filter element asset via the render:lookup tag:

<%-- Execute the Dimension filter to look up the translated asset that corresponds to the locale that the visitor requested. --%>
<render:lookup site='<%=ics.GetVar("site")%>' varname="Filter" key="Filter" match=":x" tid='<%=ics.GetVar("tid")%>' />
<render:callelement elementname='<%=ics.GetVar("Filter")%>' scoped="global"/>

25.2.5.2 About Obtaining and Maintaining a Visitor's Locale Preference

For filtering to work, you have to allow the visitor to specify a preferred language (locale). This preference must then be propagated throughout the entire site (that is, passed to all the templates).

The example below shows how this is accomplished in the FSIIWrapper element. The last section of this example shows how the locale variable is set by taking the value from the session variable (earlier in the example, we ensure that the session variable exists).

<%-- The session variable locale refers to the id of the dimension with the 
subtype of Locale that specifies which language the site is to be rendered in. 
Users can select the locale of their choice from a menu on every page of the 
site, and once selected, it is stored in session. A default locale is mapped to 
this CSElement and is set if it has not already been set. --%>
<ics:if condition='<%=ics.GetSSVar("preferred_locale") == null%>'>
<ics:then>
<render:lookup site='<%=ics.GetVar("site")%>' varname="default:locale:name" key='DefaultLocale' ttype="CSElement" tid='<%=ics.GetVar("eid")%>' match=":x"/>
<asset:load name="defaultLocale" type="Dimension" field="name" value='<%=ics.GetVar("default:locale:name")%>'/>
<asset:get name="defaultLocale" field="id" output="default:locale:id"/>
<ics:setssvar name="preferred_locale" value='<%=ics.GetVar("default:locale:id")%>'/>
</ics:then>
</ics:if>
<%-- Call the wrapped child page. There is no need to look up the template or to enable any special PageBuilder functionality, so we can use the render:satellitepage tag in this situation. --%>
<render:satellitepage pagename='<%=ics.GetVar("childpagename")%>' packedargs='<%=ics.GetVar("packedargs")%>'>
<render:argument name='c' value='<%=ics.GetVar("c")%>'/>
<render:argument name='cid' value='<%=ics.GetVar("cid")%>'/>
<render:argument name='p' value='<%=ics.GetVar("p")%>' />
<render:argument name="locale" value='<%=ics.GetSSVar("preferred_locale")%>'/>
</render:satellitepage>

25.2.5.3 About Filtering Search Results

If your online site contains search functionality, you may choose to filter the search results returned to the visitor, based on the visitor's language preference.

The following example shows how the Page/SearchDetailView template filters an IList of search results so that the query can go against all languages but only return defined results:

<%-- look up the dimension set and filter the ProductList results --%>
<asset:load name="GlobalDimSet" type="DimensionSet" field="name" value='<%=ics.GetVar("GlobalDimSet")%>' />
<dimensionset:filter name="GlobalDimSet" tofilter="ProductList" list="ProductList">
<dimensionset:asset assettype="Dimension" assetid='<%=ics.GetVar("locale")%>'/>
</dimensionset:filter>

See the Tag Reference for Oracle WebCenter Sites. Additionally, examine the code in the FirstSiteII sample site to see how it implements multilingual support.

25.3 Planning Multilingual Support for a Site

Before you start configuring multilingual support on your site, consider how many languages you need to implement at present, whether you would like to share locale and dimension sets between sites, consider how you should handle asset relationships, and so on. Make these decisions in agreement with your site administrators.

  1. Determine how many languages to initially implement on your site (or sites), based on your organization's content management needs. You can either:

    • Build a site (or sites) to support a single language initially, and add support for additional languages as the need arises.

    • Plan ahead for all the languages you expect to incorporate across all of your sites and create the appropriate locales in advance.

  2. Determine whether you will share existing locales and dimension sets to the new site (or sites), or create separate ones. See Cross-Site Multilingual Support.

  3. Decide how asset relationships are going to be handled at render time with respect to locales, and choose the locale filtering method(s) appropriate to your decision. The choices you make will have to strike a balance between levels of automation, delivery system performance, and editorial workload, and are thus best made in agreement with your site administrators. See Working with Locale Filtering. Note the following:

    • Different filtering methods provide different levels of automation at the cost of a performance hit on the delivery system. The more complex the filter, the higher the performance hit. For example, the SimpleLookup filter provides better performance than the Hierarchical filter.

    • Depending on the filtering method you implement, editorial work on site content can be spread over time, as translations can be created after the original content is created and published to the live site. The filtering logic you implement will decide what to do content that does not yet exist in the required language versions.

  4. If you are converting a monolingual site to a multilingual site, obtain the element code you will use to assign the default locale to the assets in the site. Sample code based on the FirstSiteII sample site is provided in Sample Element Code for Bulk-Assigning a Default Locale.

    Note:

    When replicating a site containing multilingual sets, make sure the master assets are available on the target site (by either sharing or copying). Otherwise, the set members will no longer be linked as translations of each other on the target site.

25.4 Configuring Multilingual Support for a Site

First thing you do is enable Dimension and DimensionSet asset types. And then you begin creating dimension sets and locales which you may share with other sites if you’ve planned to do so. When you’re configuring multilingual support, you also configure a fallback hierarchy.

These topics describe the procedures necessary to configure a site for multilingual support:

25.4.1 Configuration Quick Reference

This section provides an overview of the steps necessary to configure multilingual support for a site. Use this list as a quick reference during the configuration process.

  1. Make the necessary decisions and preparations as described in Planning Multilingual Support for a Site.
  2. Enable the Dimension and DimensionSet asset types on the site. For instructions, see Enabling the Dimension and DimensionSet Asset Types.
  3. Enable the Locale subtype of the Dimension asset type on the site. For instructions, see Enabling the Locale Subtype of the Dimension Asset Type.
  4. Create or share locales. For instructions, see the following sections:

    For help in determining whether to create locales or share existing ones, see Cross-Site Multilingual Support.

  5. Create or share a dimension set. For instructions, see the following sections:

    For help in determining whether to create a new dimension set or share an existing one, see Cross-Site Multilingual Support.

  6. (Optional) If you are converting an existing monolingual site to a multilingual site, execute element code that assigns a default locale to each asset in the site. For instructions, see How to Bulk-Assign a Default Locale to Assets in a Site. The section includes sample code which you can customize for your site.
  7. Modify the templates used in the site to include support for the locale filter you selected when you configured the dimension set. For an overview of the process, see About Adding Filtering Support to Your Site.

    Note:

    In addition to locale filtering, you will have to implement the following site functionality:

    • Allow the visitor to specify their language preference.

    • Propagate the visitor's language preference throughout the site (by passing it to all templates on the site).

    • Maintain the visitor's language preference for the duration of the session.

25.4.2 Enabling the Dimension and DimensionSet Asset Types

Before you can create Dimension and DimensionSet assets in your site, you must enable the corresponding asset types and subtypes. This procedure describes how to enable the Dimension and DimensionSet asset types on your site. The following procedure describes how to enable the Locale subtype of the Dimension asset type on your site.

  1. Open the Admin interface.

  2. Under the General Admin tree, expand the Admin node.

  3. Under the Admin node, drill down the following hierarchy:

    1. Expand the Sites node.

    2. Under the Sites node, expand the node corresponding to the site.

    3. Under the site node, expand the Asset Types node.

    4. Under the Asset Types node, double-click the Enable node.

    WebCenter Sites displays the Enable Asset Types form.

  4. In the Enable Asset Types form, select the check boxes next to the Dimension and DimensionSet asset types.

  5. Click Enable Asset Types.

    WebCenter Sites displays the Start Menu Selection form.

  6. In the Start Menu Selection form, select all of the check boxes, and click Enable Asset Types.

    WebCenter Sites displays a message confirming the asset types have been enabled for the site.

25.4.3 Enabling the Locale Subtype of the Dimension Asset Type

Before you can assign locales to assets in your site, you must enable the Locale subtype of the Dimension asset type on your site.

  1. Open the Admin interface.

  2. Under the General Admin tree, expand the Admin node.

  3. Under the Admin node, drill down the following hierarchy:

    1. Expand the Asset Types node.

    2. Under the Asset Types node, expand the Dimension node.

    3. Under the Dimension node, double-click the Subtypes node.

    WebCenter Sites displays the Subtypes for Asset Type: Dimension form.

  4. In the form, click the Edit (pencil) icon next to the Locale subtype.

    WebCenter Sites displays the Edit Dimension Subtype: Locale form.

  5. In the Sites field, select Ctrl+click for the site to enable the Locale subtype.

    Note:

    You must select Ctrl+click the name of your site to keep the existing site selections intact; if you simply click the site name, other selected sites (if any) will be deselected.

  6. Click Save.

25.4.4 How To Create a Locale

Note:

If the locale you want to create designates a language that is represented by a Dimension asset in another site in your WebCenter Sites system, share the existing Dimension asset representing that language to your current site instead to avoid redundancy.

To add a new locale to your site, create a Dimension asset of subtype Locale representing a locale, by performing the following steps:

  1. In the button bar, click New.
  2. In the list of asset types, click New Dimension.
  3. WebCenter Sites displays the New Dimension form.
  4. In the New Dimension form, do the following:

    In the Name field, enter a descriptive name for the locale. It is recommended that you use the following convention as a best practice:

    xx_YY

    where:

    • xx is the two-letter ISO 639-1 language code (for example, fr for French)

    • YY is the two-letter ISO country code (for example, CA for Canada)

    To complete the above example, the name fr_CA would denote Canadian French.

  5. In the Description field, enter a description of the language this locale represents.
  6. In the Subtype drop-down list, select Locale.
  7. Click Save.

25.4.5 How to Share a Locale to Another Site

To share a locale to another site, you must share the corresponding Dimension asset.

  1. Open the Admin interface and select the site containing the Dimension assets for the locales you want to share.

  2. Find the Dimension asset and open its Inspect form:

    1. In the button bar, click Search.

    2. In the list of asset types, click Find Dimension.

    3. Enter search criteria (if any), and click Search.

    4. In the list of search results, navigate to the asset and click its name.

      WebCenter Sites opens the asset in the Inspect form.

  3. In the action bar, select Share Dimension.

    WebCenter Sites displays the Share Dimension form.

  4. In the Share Dimension form, select the check boxes next to the sites to which you want to share the Dimension asset. (To share the asset to all sites on your WebCenter Sites system, select the All Sites check box.)

  5. Click Save Changes.

    WebCenter Sites displays a message confirming the asset is now available in the sites you selected.

25.4.6 How To Create and Configure a Dimension Set

To create and configure a Dimension set:

  1. Add the Dimension assets (locales) you want to include in the dimension set to your Bookmarks by doing the following:

    1. In the button bar, click Search.

    2. In the Search form, click Find Dimension.

    3. Enter search criteria (if any) and click Search.

    4. In the list of search results, navigate to the Dimension assets and select their check boxes.

    5. Click Add to My Bookmarks.

  2. Create and configure the dimension set by doing the following:

    1. In the button bar, click New.

    2. In the New asset list, click New DimensionSet.

      WebCenter Sites displays the New DimensionSet form.

    3. In the Name field, enter a descriptive name for the dimension set.

    4. In the tree, select the Bookmarks tab.

    5. In the Bookmarks tab, select a locale you want to add to the dimension set and click Add Selected Items. Repeat this step for each additional locale you want to add.

    6. In the Dimension Filter Class field, select the locale filter type. The Advanced option lets you specify a custom filter class.

      For information about locale filter types, see Working with Locale Filtering.

    7. (Optional) If you selected Advanced in step 2, enter the name of the custom filter class into the text box that opens.

    8. When you are finished, click Save Changes.

    9. (Optional) If you selected the Hierarchical filter in step 2, complete the steps in How to Configure the Fallback Hierarchy of the Hierarchical Filter to configure the filter's fallback hierarchy.

25.4.7 How To Share a Dimension Set to Another Site

To share a dimension set to another site, you must share the corresponding DimensionSet asset.

  1. Open the Admin interface and select the site containing the DimensionSet asset you want to share.

  2. Find the DimensionSet asset and open its Inspect form:

    1. In the button bar, click Search.

    2. In the list of asset types, click Find DimensionSet.

    3. Enter search criteria (if any), and click Search.

    4. In the list of search results, navigate to the asset and click its name.

      WebCenter Sites opens the Inspect form for the asset.

  3. In the action bar, select Share DimensionSet.

    WebCenter Sites displays the Share DimensionSet form.

  4. In the Share DimensionSet form, select the check boxes next to the sites to which you want to share the DimensionSet asset. (To share the asset to all sites on your WebCenter Sites system, select the All Sites check box.)

  5. Click Save Changes.

  6. WebCenter Sites displays a message confirming the asset is now available in the sites you selected.

25.4.8 How To Configure a Locale Filter

Usually, you configure the locale filter when you create the dimension set for your site. To make changes to the locale filter configuration in an existing dimension set, do the following:

  1. Find the dimension set whose locale filter you want to configure and open in the Inspect form:

    1. In the button bar, click Search.

    2. In the Search form, click Find DimensionSet.

    3. Enter search criteria (if any) and click Search.

    4. In the list of search results, navigate to the asset and click its name.

      WebCenter Sites opens the asset in the Inspect form.

  2. In the Dimension Filter Class field, select the option next to the filter type. The Advanced option lets you specify a custom filter class.

    For information about locale filters, see Working with Locale Filtering.

  3. (Optional) If you selected Advanced in step 2, enter the name of the custom filter class into the text field that displays.

  4. Click Save Changes.

  5. (Optional) If you selected the Hierarchical filter in step 2, complete the steps in How to Configure the Fallback Hierarchy of the Hierarchical Filter to configure the filter's fallback hierarchy.

25.4.9 How to Configure the Fallback Hierarchy of the Hierarchical Filter

If you selected the Hierarchical (Fallback) locale filter when configuring your dimension set, perform the following steps to configure the filter's fallback hierarchy:

  1. If you plan to add new locales or rearrange existing locales in the fallback hierarchy, add the Dimension assets representing the locales to be included in the hierarchy to your Bookmarks by doing the following:

    1. In the button bar, click Search.

    2. In the Search form, click Find Dimension.

    3. Enter search criteria (if any) and click Search.

    4. In the list of search results, navigate to the Dimension assets and select their check boxes.

    5. Click Add to My Bookmarks.

  2. Find and open in the Inspect form the dimension set that contains the Hierarchical filter you want to configure:

    1. In the button bar, click Search.

    2. In the Search form, click Find DimensionSet.

    3. Enter search criteria (if any) and click Search.

    4. In the list of search results, navigate to the DimensionSet asset and click its hyperlinked name.

      WebCenter Sites displays the Inspect form for the DimensionSet asset.

  3. When configuring the fallback hierarchy, note the following:

    • A locale can appear in the fallback hierarchy only once.

    • If you have to delete a locale from the hierarchy, click the Delete (trash can) icon next to the locale node.

    • If you have to change the position of a locale in the hierarchy, delete it, then add it under the parent node.

To configure the locale hierarchy:

  1. In the Dimension Filter Class field, click Configure Locale Hierarchy.

    WebCenter Sites displays the Configure Locale Hierarchy form.

  2. In the Configure Locale Hierarchy form, click Edit.

    WebCenter Sites displays an editable version of the form.

  3. In the tree, select the Bookmarks tab.

  4. (Optional) If the hierarchy is empty, select in the Bookmarks tab the locale you want to designate as the top node of the fallback hierarchy, then click Add Selected Items.

  5. Select a parent node for the locale you want to add to the hierarchy.

    If you are building a hierarchy from scratch, your only choice will be the top-level node you added in step 4.

    When building your hierarchy, keep in mind the direction in which the fallback process occurs (from most-specific to least-specific; that is, towards the root node of the tree).

  6. In the Bookmarks tab, select the locale you want to appear under the parent node you selected in step 5, then click Add Selected Items.

  7. Repeat steps 5 and 6 for each additional locale you want to add to the hierarchy.

  8. When your fallback hierarchy is complete, click Save Changes.

25.4.10 How to Bulk-Assign a Default Locale to Assets in a Site

If you are converting a monolingual site to a multilingual site, you must assign a default locale to all assets in the site. The fastest way to accomplish this is to execute an element that assigns the default locale to the assets.

For your convenience, sample element code for this procedure is provided Sample Element Code for Bulk-Assigning a Default Locale. The sample code is intended as an example, and will have to be customized for your site.

  1. Create a CSElement asset to hold the element code that will assign a default locale to your assets.
  2. Create a SiteEntry asset that references the CSElement asset you created in step 1.
  3. Call the SiteEntry asset you created in step 2 in a URL, as follows:
    http://<host>:<port>/<context>/ContentServer?pagename=
    <siteentry_name>
    

    where:

    • <host> is the host of your WebCenter Sites system

    • <port> is the port number on which WebCenter Sites is listening for connections

    • <context> is the application context root assigned to the WebCenter Sites application.

    • <siteentry_name> is the name of the SiteEntry asset you created in step 2.

    When the element code completes execution, check to ensure your assets have the locale assigned. If not, check the element code for possible errors.

25.4.10.1 Sample Element Code for Bulk-Assigning a Default Locale

This section contains sample element code written for the FirstSiteII sample site. The code does the following:

  1. Creates a Dimension asset named en_US to represent your default locale designation within the site (US English in this example).

  2. Assigns this default locale to all Page assets within the site.

    Note:

    The code in this section is provided as an example. If you decide to use it, be sure to customize it for your site. Test the code before deploying it; no error checking is included in this example.

<%@ taglib prefix="cs" uri="futuretense_cs/ftcs1_0.tld"%>
<%@ taglib prefix="asset" uri="futuretense_cs/asset.tld"%>
<%@ taglib prefix="ics" uri="futuretense_cs/ics.tld"%>
<%@ taglib prefix="render" uri="futuretense_cs/render.tld"%>
<%@ taglib prefix="user" uri="futuretense_cs/user.tld"%>

<cs:ftcs>

<%-- Record dependencies for the SiteEntry and the CSElement --%>
<ics:if condition='<%=ics.GetVar("seid")!=null%>'>
<ics:then>
<render:logdep cid='<%=ics.GetVar("seid")%>' c="SiteEntry"/>
</ics:then>
</ics:if>

<ics:if condition='<%=ics.GetVar("eid")!=null%>'>
<ics:then>
<render:logdep cid='<%=ics.GetVar("eid")%>' c="CSElement"/>
</ics:then>
</ics:if>

<%-- log in as firstsite--%>
<user:login username="firstsite" password="firstsite"/>
<%-- create the Dimension asset (this can be done manually) --%>
<asset:create name="en_US" type="Dimension"/>
<asset:setsubtype name="en_US" value="Locale"/>
<asset:set name="en_US" field="name" value='en_US'/>
<asset:set name="en_US" field="description" value='US English'/>
<%-- enter your site's pubid below --%>
<ics:setvar name="primarypubid" value="1112198287026"/> 
<asset:save name="en_US"/>

<%-- look up the id of the Dimension asset you just created --%>
<asset:get name="en_US" field="id" output="en_US.id"/>

<%-- get a list of all Content_C assets in the site, and assign a dimension to each of them --%>
<asset:list type="Content_C" list="allContentAssets" pubid="1112198287026"/>
<ics:listloop listname="allContentAssets">
<ics:listget listname="allContentAssets" fieldname="id" output="id"/>
<asset:load type="Content_C" objectid='<%=ics.GetVar("id")%>' name="tempName" editable="true"/>
<asset:adddimension name="tempName" dimensionid='<%=ics.GetVar("en_US.id")%>'/>
<asset:save name="tempName"/>
</ics:listloop>
</cs:ftcs>

25.5 Tips for Using WebCenter Sites Translation Mechanism

Here are some tips that you can use to address some common translation scenarios on your site.

The common two basic scenarios are:

  • Editorial teams create and publish content in a primary language first, and then translate and publish translations/localizations as needed in an ad-hoc manner.

  • Editorial teams create content and translate it together as a package. When completed, they publish the package all at once.

25.5.1 What Do Customers Want?

  • Ability to create content in a master language, wire it up to other related content (which may or may not be in the master language), then either publish it and translate it later, or

  • Translate the content and other related bits and pieces, and then publish the whole as a single package.

  • Flexibility to apply country-specific rules to the rendered content.

25.5.2 Use of WebCenter Sites Translation Mechanism to Effectively Meet Customers' Requirements

WebCenter Sites has a built-in translation mechanism which uses an assettype called DimensionSets. As a practice, all translated versions of the same content belong to the same DimensionSet instance. This feature also enables designing a fallback tree of locales. When the current locale does not have translated content, another translation which may be available is displayed as the fallback version. A single DimensionSet can contain each locale only once. Using the same locales in a different sequence for different countries is not allowed.

Creating Translations Using Multiple Dimensionsets

To remedy this situation, developers can create different DimensionSets for each country so that they can define an independent fallback logic for each of them. For example, customers would not want to show any English contents on a site like that of France. Whereas a customer based out of The Netherlands would like to include English contents on his site in addition to those in Dutch. In other words, different countries require different fallback mechanisms.

Hence, if a site is targeted toward 20 countries, then there would be 20 DimensionSets (with perhaps 30 or 40 or more locales in total). To support multiple DimensionSets, the rendering template code should be able to determine which DimensionSet to use. The translate tags require the DimensionSet name for the current translation. The following two properties make it possible to use multiple DimensionSet:

  • The name of the DimensionSet is the value of the country code. For example, uk for the United Kingdom, de for Deutchland, and so on.

  • All web-referenceable assets have a URL path that explicitly includes the country code (for example, www.mysite.com/uk/helloworld, and www.mysite.com/de/helloworld, or alternatively one can support different subdomains such as uk.mysite.com/helloworld, and so on.

Note:

It is generally considered a bad practice to render different content for the same URL for different users based on their accept-language value or IP geo-location. The reason is that SEO rankings are likely to drop as search engines such as Google may consider such a strategy as a form of bait-and-switch.

With the above two features in place, developers just parse the URL request to extract the country value then pass the country value as an additional argument which can then be used by the Template to specify which DimensionSet to use for the current asset. (It is common for some customers to choose a primary site that has no country code which we can assume is the default.)

Another option is that our code honors the preferred locale cookie which the visitor may have set on their browser.

When Customers Want the Same Content on Websites on Which Other Languages are Used

Some customers want virtual URLs to be supported wherein an asset can be published as …/us/helloworld. These customers also want that the same content is rendered (without needing to translate it) on other English-speaking country sites, for example, …/uk/helloworld, …/ca/helloworld, …/au/helloworld, and so on. The latter requirement can be handled by creating a global (or master) version of an asset. So instead of including only ISO locales in our DimensionSet hierarchy, developers can include made up locales as required. The following CH (Switzerland) DimensionSet: example explains the use of global DimensionSets:

global
en_GLOBAL
en_CH
de_GLOBAL
de_CH
fr_GLOBAL
fr_CH

The above hierarchical DimensionSet can work as follows:

  • When editors require locale-specific differences they can make ad-hoc localized translations as needed. For example, en_CH, de_CH, or fr_CH.

  • When language-specific differences need to be available to other DimensionSets, developers can make ad-hoc global translations instead. For example, en_GLOBAL, global-de, fr_GLOBAL, and so on.

A fixed hierarchy like the above does not provide the ability to have exceptions to the fallback logic.

The above example can be extended to also include a regional fallback, for instance, Latin American Spanish es_LAD and South Asian English en_AS. This allows marketing to create content that is localized for a Latin America audience and syndicate this content to many country sites without displaying it on other international sites as it would if en_GLOBAL were used.

Enabling Search for Locale-Specific Content

How do query-based searches compile and render lists of assets on a per-locale basis while taking into account all the various fallback logics? For example, if a visitor is on a French webpage, probably they only want to see contents that are either fr_FR or fr_GLOBAL. Duplicate translations in the same DimensionSet should be avoided.

Solution

For queries to return dynamic lists of assets based on searchable attributes, the assets must have attributes that can be used to constrain the search to a specific locale. To enable this, we must convert each asset's selected locale (which is not an attribute as such) into a multi-valued attribute named SearchableLocale via a custom flex filter. For instance, an asset whose locale is fr_FR, store a single value of SearchableLocale=fr_FR since for most clients fr_FR would be at the leaf node of the fallback hierarchy for France. However, an asset whose locale is fr_GLOBAL should store fr_FR as well as any other French-speaking locales across all French-speaking countries. In this way, this global French asset can show up on multiple French language sites via any constrained queries. As an example, for a European-only website, a fr_GLOBAL asset would upon save create both fr_FR and fr_CH SearchableLocale values via its flex filter and thus show up on the France (FR) and Switzerland (CH) sites.

Note:

The above denormalization of fallback values into an asset attribute allows you to perform fewer queries at runtime. When marketing requires changing the fallback logic, all data values need to be recomputed. Proceed with caution when designing your solution.

Hiding a Global Asset on Certain Countries Sites

Many customers desire the flexibility to hide a global asset from certain countries. Thus a HideFromTheseCountries attribute should be added to the definition for each translatable asset. A custom attribute editor should also be created to restrict the list of countries shown in the editorial interface on which the current asset can be hidden based on the locale selected. That is, if the current locale were fr_FR, then the list of countries to hide would be null. Whereas if the locale chosen were fr_GLOBAL, the list of countries might include FR, CH, and so on -- depending on the number of DimensionSets created to support the all the country sites.

With the combination of the custom HideFromTheseCountries attribute/attribute editor and a custom flex filter that denormalizes the optimized locales as multi-valued SearchableLocale attribute, any queries in rendering Templates only need to add the current locale as a constraint. For example, on a webpage whose locale is fr_FR, you might want to show the Latest News in a right-rail pagelet. This pagelet will query the News assets where locale=fr_FR and sort the list by date. There might be duplicates since the fr_GLOBAL asset is also translated into fr_FR and thus both are returned in the list. To remove duplicates, use the translate tag <dimensionset:filter> which takes an iList from the constrained query that filters out duplicates.

Handling Caching Issues

If you publish all translations at once, any change to any existing translation will cause those pagelets dependent on that asset to expire at publish time. If you publish a global version of a language, and then later create localized versions of that asset, the system will not know to update things since no dependencies were recorded at the last rendering of the pagelet.

A simple example is, let us say a list of the latest press releases on a French page, and let's also assume that all of the assets being rendered are fr_GLOBAL. We can even further assume that the links are explicitly defined as named associations, thus all the dependencies are known at the time of rendering/caching. When someone translates one of those assets and publishes it, the desired behavior is that the link would now be to the localized translation, not to the global version. But because there is no way to log a dependency to an asset that did not exist when that pagelet was last rendered, there is no way for the system to know to update that one link. And thus nothing uncaches when you publish the new translation.

The simple solution is to update the master asset whenever a new child is added to a DimensionSet. To do this, one must implement a custom publish listener that performs these tasks in the background whenever a new asset is published that might affect an existing DimensionSet. There is no need to update the master asset when a new translation is created because it might take days or weeks before the asset gets approved and published.

Also be aware that any automatic approval mechanism must also deal with the situation where the master asset may be checked out or not yet approved.