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:
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:
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.
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.)
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). 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.
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 Reference, 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.
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.
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:
|
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. |
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:
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.
Understanding the Included Locale Filters
WebCenter Sites ships with the following locale filters:
-
The Hierarchical Filter (also known as the Fallback filter)
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.
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.
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.
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).
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.
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:
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.
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
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 thec/cid
of thec1en
asset, then render its children without filtering theirc/cid
values, because we trust thec1en
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:
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"/>
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>
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 Reference. Additionally, examine the code in the FirstSiteII sample site to see how it implements multilingual support.
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.
-
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.
-
-
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.
-
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.
-
-
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.
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:
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.
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.
-
Open the Admin interface.
-
Under the General Admin tree, expand the Admin node.
-
Under the Admin node, drill down the following hierarchy:
-
Expand the Sites node.
-
Under the Sites node, expand the node corresponding to the site.
-
Under the site node, expand the Asset Types node.
-
Under the Asset Types node, double-click the Enable node.
WebCenter Sites displays the Enable Asset Types form.
-
-
In the Enable Asset Types form, select the check boxes next to the Dimension and DimensionSet asset types.
-
Click Enable Asset Types.
WebCenter Sites displays the Start Menu Selection form.
-
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.
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.
-
Open the Admin interface.
-
Under the General Admin tree, expand the Admin node.
-
Under the Admin node, drill down the following hierarchy:
-
Expand the Asset Types node.
-
Under the Asset Types node, expand the Dimension node.
-
Under the Dimension node, double-click the Subtypes node.
WebCenter Sites displays the Subtypes for Asset Type: Dimension form.
-
-
In the form, click the Edit (pencil) icon next to the Locale subtype.
WebCenter Sites displays the Edit Dimension Subtype: Locale form.
-
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.
-
Click Save.
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:
How to Share a Locale to Another Site
To share a locale to another site, you must share the corresponding Dimension asset.
-
Open the Admin interface and select the site containing the Dimension assets for the locales you want to share.
-
Find the Dimension asset and open its Inspect form:
-
In the button bar, click Search.
-
In the list of asset types, click Find Dimension.
-
Enter search criteria (if any), and click Search.
-
In the list of search results, navigate to the asset and click its name.
WebCenter Sites opens the asset in the Inspect form.
-
-
In the action bar, select Share Dimension.
WebCenter Sites displays the Share Dimension form.
-
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.)
-
Click Save Changes.
WebCenter Sites displays a message confirming the asset is now available in the sites you selected.
How To Create and Configure a Dimension Set
To create and configure a Dimension set:
-
Add the Dimension assets (locales) you want to include in the dimension set to your Bookmarks by doing the following:
-
In the button bar, click Search.
-
In the Search form, click Find Dimension.
-
Enter search criteria (if any) and click Search.
-
In the list of search results, navigate to the Dimension assets and select their check boxes.
-
Click Add to My Bookmarks.
-
-
Create and configure the dimension set by doing the following:
-
In the button bar, click New.
-
In the New asset list, click New DimensionSet.
WebCenter Sites displays the New DimensionSet form.
-
In the Name field, enter a descriptive name for the dimension set.
-
In the tree, select the Bookmarks tab.
-
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.
-
In the Dimension Filter Class field, select the locale filter type. The Advanced option lets you specify a custom filter class.
-
(Optional) If you selected Advanced in step 2, enter the name of the custom filter class into the text box that opens.
-
When you are finished, click Save Changes.
-
(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.
-
How To Share a Dimension Set to Another Site
To share a dimension set to another site, you must share the corresponding DimensionSet asset.
-
Open the Admin interface and select the site containing the DimensionSet asset you want to share.
-
Find the DimensionSet asset and open its Inspect form:
-
In the button bar, click Search.
-
In the list of asset types, click Find DimensionSet.
-
Enter search criteria (if any), and click Search.
-
In the list of search results, navigate to the asset and click its name.
WebCenter Sites opens the Inspect form for the asset.
-
-
In the action bar, select Share DimensionSet.
WebCenter Sites displays the Share DimensionSet form.
-
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.)
-
Click Save Changes.
-
WebCenter Sites displays a message confirming the asset is now available in the sites you selected.
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:
-
Find the dimension set whose locale filter you want to configure and open in the Inspect form:
-
In the button bar, click Search.
-
In the Search form, click Find DimensionSet.
-
Enter search criteria (if any) and click Search.
-
In the list of search results, navigate to the asset and click its name.
WebCenter Sites opens the asset in the Inspect form.
-
-
In the Dimension Filter Class field, select the option next to the filter type. The Advanced option lets you specify a custom filter class.
-
(Optional) If you selected Advanced in step 2, enter the name of the custom filter class into the text field that displays.
-
Click Save Changes.
-
(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.
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:
-
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:
-
In the button bar, click Search.
-
In the Search form, click Find Dimension.
-
Enter search criteria (if any) and click Search.
-
In the list of search results, navigate to the Dimension assets and select their check boxes.
-
Click Add to My Bookmarks.
-
-
Find and open in the Inspect form the dimension set that contains the Hierarchical filter you want to configure:
-
In the button bar, click Search.
-
In the Search form, click Find DimensionSet.
-
Enter search criteria (if any) and click Search.
-
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.
-
-
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:
-
In the Dimension Filter Class field, click Configure Locale Hierarchy.
WebCenter Sites displays the Configure Locale Hierarchy form.
-
In the Configure Locale Hierarchy form, click Edit.
WebCenter Sites displays an editable version of the form.
-
In the tree, select the Bookmarks tab.
-
(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.
-
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).
-
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.
-
Repeat steps 5 and 6 for each additional locale you want to add to the hierarchy.
-
When your fallback hierarchy is complete, click Save Changes.
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.
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:
-
Creates a Dimension asset named
en_US
to represent your default locale designation within the site (US English in this example). -
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>
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.
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.
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
, andwww.mysite.com/de/helloworld
, or alternatively one can support different subdomains such asuk.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
, orfr_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.