The document outlines a framework for managing multi-locale websites using IBM Workplace Web Content Management. The key elements of the framework include:
1. Storing each localized site in its own library to keep site structures synchronized.
2. Using workflows to manage all content modifications and automate parts of the localization process.
3. Sharing templates, components, and as much site structure across locales as possible.
4. Providing authoring tools to localize content and preview sites, as well as workflows to synchronize key stages like publishing and expirations between locales.
5. Developing a presentation layer that can deliver localized content automatically based on locale detection or through user selection of locale.
1. Multi-locale Site Management with IBM Workplace Web Content Management
October 2007
Multi-locale site management with
IBM® Workplace Web Content
Management™
Mark Hampton
Product Architect, Web Content Management
Australia Development Lab, Sydney
David de Vos
Lab Product Specialist, Web Content Management
Australia Development Lab, Sydney
Melissa Howarth
Lab Product Specialist, Web Content Management
Australia Development Lab, Sydney
2. Contents
What will this white paper help you achieve? .................................................................................................... 6
What is a multi-locale site? ................................................................................................................................ 8
The base site ..................................................................................................................................... 8
Translated sites ................................................................................................................................. 8
Regional sites .................................................................................................................................... 9
Translated regional sites ................................................................................................................... 9
Mixed-language sites....................................................................................................................... 10
Managing a multi-locale site with Web Content Management ......................................................................... 11
Framework for multi-locale site management .................................................................................................. 12
Use one library per locale ................................................................................................................ 12
Same site structure in each locale................................................................................................... 12
Use workflow for all modifications ................................................................................................... 13
Use shared templates and components .......................................................................................... 13
Authoring.......................................................................................................................................................... 15
Localization of authoring content ..................................................................................................... 15
Names and Titles ...................................................................................................................... 15
Other fields................................................................................................................................ 15
Authoring Templates ....................................................................................................................... 16
Common Authoring Templates ................................................................................................. 16
Localized Authoring Templates................................................................................................. 16
Single Authoring Templates ...................................................................................................... 17
Preview ............................................................................................................................................ 17
Lifecycle and synchronization.......................................................................................................................... 18
Creating/updating/moving localized content.................................................................................... 19
Creating..................................................................................................................................... 19
Updating.................................................................................................................................... 19
Moving....................................................................................................................................... 20
Publishing synchronization .............................................................................................................. 21
Expiry synchronization..................................................................................................................... 21
Deletion synchronization ................................................................................................................. 21
Presentation..................................................................................................................................................... 23
Presentation templates .................................................................................................................... 23
Site / site area elements .................................................................................................................. 24
Dot notation ..................................................................................................................................... 24
Localized navigator components ..................................................................................................... 25
Localized menu components ........................................................................................................... 26
Synchronizing components using workflow..................................................................................... 26
Localized site searching .................................................................................................................. 27
Localized rendering.......................................................................................................................................... 29
Auto-localization .............................................................................................................................. 29
3
3. URL ........................................................................................................................................... 29
Browser preference................................................................................................................... 29
Portal......................................................................................................................................... 29
Limitations ................................................................................................................................. 30
User-selected localization................................................................................................................ 30
Locale selection page ............................................................................................................... 31
Equivalent page navigation ....................................................................................................... 31
Some suggested options ................................................................................................................. 31
Option 1..................................................................................................................................... 32
Option 2..................................................................................................................................... 32
Encoding.......................................................................................................................................... 32
Font face considerations ................................................................................................................. 33
Deployment...................................................................................................................................................... 34
Centralized deployment ................................................................................................................... 34
Paths option .............................................................................................................................. 34
Multiple domains option ............................................................................................................ 34
Decentralized deployment ............................................................................................................... 35
Item-by-item localization navigation .......................................................................................... 36
Locale home page navigation ................................................................................................... 36
Deployment best practices .............................................................................................................. 37
Administration .................................................................................................................................................. 38
Sample code for authoring, workflow, and rendering ...................................................................................... 39
Installation and configuration ........................................................................................................... 39
Required WEB CONTENT MANAGEMENT Version ................................................................ 39
Set up the configuration library ................................................................................................. 40
Install the workflow polling application ...................................................................................... 42
Samples........................................................................................................................................... 45
Edit-time navigation/Creation sample ....................................................................................... 45
Update notification sample........................................................................................................ 48
Publishing synchronization sample ........................................................................................... 50
Expiry synchronization sample.................................................................................................. 50
Deletion synchronization sample .............................................................................................. 51
Servlet Render-time navigation sample .................................................................................... 52
Portlet Render-time navigation sample ..................................................................................... 53
Domain Locale Redirection sample .......................................................................................... 54
Where to go from here ..................................................................................................................................... 56
Locale owner decision points .......................................................................................................... 56
Per-locale configuration ................................................................................................................... 56
Regional sites synched with multiple translations ........................................................................... 57
Mixed-language site navigation ....................................................................................................... 57
Side-by-side preview ....................................................................................................................... 58
Side-by-side editing ......................................................................................................................... 58
Localization of authoring templates ................................................................................................. 59
4
4. Adding new localization settings to the Sync-Update sample ......................................................... 59
Writing your own workflow poller ..................................................................................................... 60
Disabling a workflow poller .............................................................................................................. 60
Writing your own Context Processor ............................................................................................... 61
Conclusion ....................................................................................................................................................... 62
Appendix .......................................................................................................................................................... 63
Adding JSPs to the Web Content Management Local Rendering portlet........................................ 63
Adding JSPs to the Web Content Management Authoring UI portlet .............................................. 63
Adding JSPs to the Web Content Management EAR file ................................................................ 64
Resources........................................................................................................................................................ 66
About the authors ............................................................................................................................................ 67
5
5. What will this white paper
help you achieve?
H I G H L I G H T S
T his white paper outlines a framework for using IBM® Workplace
Web Content Management™ 6.0 (hereafter called Web Content
Management) to manage and deliver localized Web sites. This
framework is based on a data structure that supports storage of
localized sites and the use of extension points in the Web content
management system for authoring, workflow, and rendering of localized
Design and build a sites.
solution for
We demonstrate how to use Web Content Management to support the
authoring and typical scenarios for site localization, scale this up to large numbers of
synchronizing localized sites, and then tailor a solution to meet your authoring, workflow,
localized content delivery, and deployment needs.
Design and build a
A set of sample code fragments is provided in the Downloads section of the
solution for
title page, to accelerate your site rollout. You will be able to install and
presenting localized configure these samples and see a basic but comprehensive multi-locale
sites site implementation in action.
Design and build a
deployment and
Once you have learned to apply the principals and framework outlined in
this paper, you will be able to design and build the following:
delivery
architecture for An authoring solution that provides your authors and site
multi-locale sites administrators with the tools they need to create and manage your
multi-locale sites
A lifecycle and synchronization solution to tie in with your processes
for managing the lifecycle of your multi-locale sites
A presentation solution for presenting content appropriately in each
locale
A deployment solution that fits into and supports your enterprise
architecture
6
6. A multi-locale delivery solution to allow your site visitors to either
select their preferred locale or be automatically shown localized
content (see figure 1)
Figure 1. Multi-locale site management framework
Authoring Workflow plug-in for Recommend Recommend Auto locale-
template plug- synchronization ations for ations for detection
in Recommendation Localized localized site sample
for lifecycle presentation deployment Locale
management templates navigation
through workflows and samples
components
7
7. 2
What is a multi-locale site?
H I G H L I G H T S
A multi-locale site consists of a base site structure and content set that
has been “localized” to support multiple audiences in multiple
locales. A locale is defined as a language or a region, or a
combination of both.
You may be localizing your site to serve a global customer base, or because
Base “master” site
your site operates in a region where your customers speak a number of
different languages.
Translated sites
synchronized with Typically a site is translated so that each page in your site has an equivalent
the base version in each language. You can cater to regional differences by including
Regional sites re- only a subset of content that is relevant for the region (country, state, or
some other regional division), and by possibly including extra regional-
using translated
specific content.
content
The base site
The base site is a “master” site structure with content that is either translated
or regionally localized, or both. Translation and selective re-use of this
structure and content is how localized sites are built and maintained. This is
an ongoing process as the base site’s structure and content are modified
over time.
A special type of base site exists when a once-off copy is made to create a
localized site, and from that point on the localized site never resynchronizes
with the base. This may be appropriate especially for a regional site that is
managed independently by a local team. The team may want to be very
selective about including content from the base site, and so it uses a manual
process for including new or updated content.
Translated sites
In a typical translated site neither the structure nor the content differs; the
content is simply translated one-for-one into multiple languages. By
8
8. translating the site in its entirety you can navigate backward and forward
between equivalent content in each language. In this use case there are
often legal and/or ethical reasons for ensuring that the content in each
language is truly equivalent and is kept in sync over time.
A partially translated site is a special case in which only parts of the site are
translated. This may be due to translation expense; translating the site
would simply not make business sense, and so only a subset of the site is
translated.
Regional sites
In a typical regionally localized site, both the structure and content vary by
region. If the regional sites have no common structure or content, they are
simply separate sites; in this scenario, there is no “multi-locale site” to
manage, and the framework described in this document is not required.
Often, however, there is some commonality, and the majority or even all of
the site structure is common, and the majority of the content may be
common; that is, it is re-used from the base site. The owners of the regional
sites would be responsible for deciding what parts of the base site structure
or content would be reused versus built especially for the region.
Translated regional sites
This is a combination of the above cases, whereby the regional sites are in
various languages and typically some of the regions use the same
language. In this case the base site must then be translated, and then the
appropriate translation re-used in the appropriate regions along with
regional content written in the local regional language.
The sample code supplied with this paper does not attempt to support a
two-tiered approach in which base content is translated and then translated
content is copied or linked into regional sites. This would be a rudimentary
extension to this code.
There may be some regions that require only a single language, and other
regions (for example, Canada, Switzerland) that require multiple languages.
The workflow samples explained in this paper do not cater to this particular
scenario either, but this is also a simple extension (see figure 2).
9
9. Figure 2. Multi-locale sites
The base locale
containing the
original site
Translated locales – as
Regional locales, some of
many languages as
which may have multiple
required to best serve
languages
your customers
Multiple regions may share
the same set of translated
content *
* Note: not covered in sample code
Mixed-language sites
Another type of multi-locale site that can exist is a mixed-language site. In
this type of site, there is not a clear distinction between the versions of the
Web site, with content in multiple languages pulled in some meaningful way
into the base site.
The audience of such a site is likely to be bilingual, but the base language is
not their native one. Key content is provided for them in their language, and
navigational aids throughout the site help them discover which content has
been translated and how to find more information on topics that have not
been translated.
The general framework outlined in this document is still useful in these
cases; authoring and workflow in particular would be similar to a fully
localized site. The differences will be in the presentation system, in which
navigation must be built to support the mixed language site. Ideas for how
this can be implemented are discussed in the “Where to go from here”
section.
1 0
10. 3
Managing a multi-locale site with
Web Content Management
H I G H L I G H T S
M
content.
anaging a multi-locale site, whether it is a translated site, regional
site, or both, requires steps to be built into your site maintenance
process for deploying new localized sites, ongoing authoring of
localized sites, and synchronization of shared structure and
Manage and deliver
Delivery of a multi-locale site requires logic to be built into your presentation
layer to provide either automatic or user-driven localized content delivery;
translated,
that is, you can either detect locale automatically or ask the site visitors to
regionally localized pick.
sites
Automate key areas Web Content Management helps in both management and delivery by
of management and
allowing you to plug code into the authoring, workflow, and presentation
systems to provide a comprehensive multi-locale content management
delivery
solution.
1 1
11. 4
Framework for multi-locale
site management
T he framework in this white paper covers a data model for storing
multi-locale sites, the processes for managing multi-locale sites,
and a model for delivering multi-locale sites to site visitors.
To accompany the outlined framework, a set of sample code fragments are
provided to enable you to get up and running quickly with your multi-locale
solution.
H I G H L I G H T S The key elements of this framework are described below and illustrated in
figure 3.
Store sites in
Use one library per locale
localized libraries
Keep localized
library structures in Libraries are the partitioning construct in a Web Content Management
sync repository, providing a point where locale assignment, role assignment, and
syndication are managed.
Use workflow for all
modifications You should create a library for the base site, one library for each localized
Use shared site, and a library for shared templates and components (non-localized
templates and assets).
components
When creating libraries, ensure that the correct locale is specified during the
creation process, as this locale is used during search and in the multi-lingual
samples.
Same site structure in each locale
For content to be recognized as being equivalent, it must have the same
path in each locale library (display titles can be different, of course).
1 2
12. Use workflow for all modifications
You should perform creating, updating, publishing, expiring, deleting, and
even moving content by using workflow. This allows code triggered by the
workflow to notify localized site owners, automate parts of the localization
process, and synchronize important stages in the workflow.
You can localize workflows by creating an equivalently named workflow in
each locale library (see figure 3). Localizing the workflow allows separate
approval processes to be executed per locale and is also a requirement for
the regional locale / translation process discussed in the “Where to go from
here” section. Localizing the workflow is part of synchronization process,
and the provided sample code for workflow synchronization has this ability.
Use shared templates and components
Authoring templates, presentation templates, and components should be
shared across locales as much as possible. You can build in variability by
using workflows or workflow code that differ across locales and by using
presentation components that are picked up from the current locale.
If necessary, you can make presentation templates different across locales
by simply having different mappings in each locales; though it should be
avoided to ensure consistency across locales, major differences in layout or
branding in some locales may necessitate this.
Authoring templates can be varied across locales too, but this is more
difficult to deal with as it complicates querying, creating, copying, etc. of
content. This white paper and the accompanying samples assume that the
authors in each locale understand the base locale language, and therefore
localized templates are not required.
1 3
14. 5
Authoring
N early all authoring tasks are initiated in the base site and are then
replicated, if appropriate, in all the localized sites. An exception to
this rule is regional content that will never be used in another
localized site or “fixes” (for example, spelling mistakes or poor
translations) that are applied only in a single localized site.
Localization of authoring content
While the initial creation of both the base locale document and any
localizations can be done manually via the Web Content Management
Authoring Interface, it’s recommended to use either a custom authoring field
(with appropriate logic) or Workflow Synchronization code to automate the
initial creation of localized documents (in the base locale language) that can
then be translated by the appropriate team.
N A M E S A N D T I T L E S
When you perform the translation, be careful not to translate the Name field
in the Identification section as doing so will break the link between the
translated document and its base copy.
The translators are free to translate the Display Title field, and this should be
encouraged to let links be displayed using the correct translation of the
content name.
NOTE: The Edit-time navigation/Creation sample demonstrates how to
create the initial localized content (in the base locale language) from a
custom authoring field, whereas the Sync Update Workflow Synchronization
sample demonstrates the same functionality from a Workflow
Synchronization point of view. Both can be used together.
O T H E R F I E L D S
Other fields may be different between locales, but for the purposes of
consistency with respect to availability and access, many of the metadata
1 5
15. fields are typically kept in sync, including authors, categories, publish date,
expiry date, security.
The “owner” field may be localized to indicate the owner of the specific
localization. This can be used during automated workflow code to notify the
appropriate users of updates.
Note that the sample code does not attempt to re-sync fields on updates,
nor does it utilize the owner field (assuming that each locale has a single
owner). These are rudimentary modifications to make to the sample code.
Authoring Templates
There are multiple ways in which authoring templates can be set up in a
multi-locale environment, each with their own pros and cons. Each method
works, but the common authoring template model is what is recommended.
C O M M O N A U T H O R I N G T E M P L A T E S
Having a common authoring template is the recommended approach to
setting up authoring in a multi-locale environment. Common authoring
templates should be created in the common library and used for all locales.
This means that authors in each locale need to understand the base locale
language since element names are not localized. The Help fields could
perhaps contain help in multiple languages, if required.
L O C A L I Z E D A U T H O R I N G T E M P L A T E S
Localized authoring templates involve each locale having its own authoring
templates with translated element names, Help, etc. This approach is not
recommended because of the following:
• Querying content is more complicated; each of the equivalent
templates would need to be listed in shared menus or rules
• Creating content is more complicated; the user must choose the
appropriate template for the type of content and locale
• The lack of Web Content Management API support for authoring
templates means that localized authoring templates can’t be
automatically synchronized (although simple workflow processes
may still be used to notify template owners of changes)
• We can usually assume that the authors/translators understand the
base language
If there is a sufficiently compelling reason to translate the templates,
including element names, Help text, default values, etc., then it is
recommended that you implement this by putting the localized templates in
the appropriately localized libraries. See “Localization of authoring
templates” in the Where to go from here section for more details.
1 6
16. S I N G L E A U T H O R I N G T E M P L A T E S
This approach involves the use of a single authoring template with fields for
each locale. This approach is not recommended for the following reasons:
• Not scalable (only a limited number of languages could be supported
due to the number of fields on the authoring template)
• Cannot have content authors editing localizations concurrently
• Localizations cannot be syndicated separately
• Only a single workflow can be used
• Localized content cannot be published/expired independently
• Cannot use non-Unicode character sets
Preview
To preview how the content will look in the specified locale, including the
appropriate encoding, portal themes etc., you should preview from within the
appropriate library.
1 7
17. 6
Lifecycle and synchronization
W
figure 4).
orkflow (plus some custom code) can be used to keep the base
site and localized sites in sync; specifically, you can synchronize
creation, modification, publishing, expiry, deletion, and moving of
site areas and content across locales by using workflow (see
Although you can have custom code run when documents enter a workflow
stage by periodically calling the Web Content Management API
findContentByWorkflowStage method, it’s recommended that any custom
code use the Workflow Polling Framework delivered with the sample code,
Figure 4. Workflow for locale synchronization
as it makes this job easy.
Where and when appropriate, a locale owner may of course choose to not
utilize some base site areas or content, or may choose to ignore or
1 8
18. otherwise treat differently any particular update that occurs to the base site.
The Workflow Synchronization code should handle this condition.
Creating/updating/moving localized content
To keep content synchronized between locales, a special workflow stage to
handle the updating, moving, and creation of content in the base library
should be created that runs some custom code after the approval stage. If
the current content document has already been published, the action should
be considered an update or move. It is treated as new content if no
published version exists.
C R E A T I N G
When new content is created in the base library, the workflow
synchronization code should run one of the following actions (see figure 5)
against each configured localized library and then send a notification to all
affected localized library owners:
• The content is copied into the library for later translation OR
• The content is linked into the library for non-translated use OR
• The library is ignored (it is neither copied nor linked into the library)
Figure 5. Synchronized creation options
Note: The Sync Update Workflow Synchronization sample demonstrates
this functionality.
U P D A T I N G
When content is updated in the base library, the workflow synchronization
code should create draft copies of existing published localized content and
send a notification to all affected localized library owners (see figure 6).
1 9
19. Figure 6. Synchronized update
Note: The Sync Update Workflow Synchronization sample demonstrates
this functionality
M O V I N G
When moving content in the database library, rather than move the
published content, the author/owner should first create a draft copy of the
published content and then move the draft to the correct location.
Figure 7. Synchronized move
When the draft content is detected as moved within the base library by the
workflow synchronization code (because its associated published version is
under a different site area), draft copies of the existing published localized
content should be created and moved to the corresponding location in the
localized library (see figure 7). A notification should then be sent to all
affected localized library owners.
Note: The Sync Update Workflow Synchronization sample does not
demonstrate this functionality but could be extended to do so.
2 0
20. Publishing synchronization
To ensure that the base item and localized items are published at the same
time, another special workflow stage is required. This workflow stage runs
more custom code after the approval and Create/Update/Move
synchronization stages and before the actual Publish workflow stage.
When documents are processed in this stage by the workflow
synchronization code, they will only be moved to the next stage (which will
do the actual publishing) if every draft localized copy is in this stage. A
notification should be sent to all affected localized library owners when
documents leave this stage.
Note: The Sync Publish Workflow Synchronization sample demonstrates
this functionality.
Expiry synchronization
To ensure that the base item and localized items are expired at the same
time, yet another special workflow stage is required. This workflow stage
runs also runs some custom code after the Publish workflow stage.
When documents are processed in this stage by the workflow
synchronization code, they will only be moved to the next stage (which will
do the actual expiration) if every published localized copy is in this stage. A
notification should be sent to all effected localized library owners when
documents leave this stage.
Note: The Sync Expire Workflow Synchronization sample demonstrates this
functionality
Deletion synchronization
If a base item is deleted, the localized content should also be deleted. To
handle this, another special workflow stage is required (to run the
associated custom code). This stage should be either after the Expiry stage
(if content expiration is used) or after the Publish stage (if content expiration
isn’t used).
Therefore, to delete an item, you need to push the document to the final
workflow stage, which typically only a site administrator or Web Content
Management administrator would be able to do.
When the workflow synchronization code processes documents in this
stage, if the base item is detected (or no base item exists), then all draft,
published, and expired localized copies should be removed and a
notification sent to all affected library owners informing them of the deletion.
If a localized item is detected and the base item is in another stage, then a
“Deletion Request” notification should be sent to the base library owner
informing him that various localized copies wish to be deleted.
2 1
21. Note: The Sync Delete Workflow Synchronization sample demonstrates this
functionality.
2 2
22. 7
Presentation
L ocalizing the presentation layer in your site is a matter of deciding
which parts of the presentation layer need to be localized, and then
pulling those pieces out into components that can be localized.
Remember to use the Display Title attribute rather than the Name attribute
when displaying the name of content as the latter is not localized and will
result in information being shown in the wrong locale.
Presentation templates
In many cases you can use the same presentation templates in all locales,
and you can vary fragments of the template by using one of these two
options:
• From the current site / site area: Localized components can be
referenced from the current site or site area (discussed below).
• Using the dot (“.”) notation when referencing components: This is
evaluated to mean “get the named component from the current
library” (also discussed below).
In other cases, however, a locale requires such different presentation that
you must use an entirely different template; for example, to support locales
with languages that read right to left, or for locales with very different
branding.
You can use all these strategies together by setting up template mappings
appropriately in each localized site and using site / site area elements or dot
notation where appropriate.
2 3
23. Site / site area elements
Using site or site area element to vary the locale presentation is most
suitable for parts of the presentation that are basically content; that is, for
site-specific content that needs to change per locale /site / site area. Table 1
outlines the pros and cons of this element.
Table 1. Site / site area pros and cons
P R O S C O N S
• Author focused; user needs only • Not a good solution for fragments
to be a site manager to edit these of the presentation template that
elements are actually under the control of
the designer rather than the site
• Can use a level of indirection, manager
where the site manager selects
different pre-built components • Not good for large number of
elements; too many (12+) may
• If the site or site area is cause scalability issues
workflowed, all the modified
elements may be previewed at
once
• Good for multiple sites per locale
Dot notation
The dot (“.”) notation (see the IBM WebSphere® Portal Information Center’s
Referencing Components section for the format) is most suited to the more
“hard-coded” locale-specific design variations in a presentation template;
that is, those that do not need to be managed like content. The user
managing the presentation layer would vary these depending on factors like
translated text, locale-specific colors, or other branding, locale-specific
layout. Table 2 outlines the pros and cons.
2 4
24. Table 2. Dot notation pros and cons
P R O S C O N S
• Designer focused; most likely • Cannot preview changes easily
under the control of the same
users managing the presentation • View references not available
templates
• User roles can be used to lock
down who may modify
components
• Can scale to large number of
components (there are many
locale points of variance in the
template)
Localized navigator components
Structural differences between localized sites can be picked up by navigator
components.
If you use the “Current site,” “Current site area,” and “Current content”
options, you can re-use navigators across sites easily. This typically covers
most navigation like Site maps, Breadcrumbs, Current area content, etc.
Navigators that use “Selected” start positions cannot easily be shared
across locales; instead, these would need to be pulled in via the dot notation
to retrieve localized components. Note that the design elements for these
navigators can still be shared appropriately to reduce maintenance.
Another way of localizing a navigator is to use a JSP fragment to set a
different context before rendering the navigator. Set the navigator to use the
“Current site area” as the starting point, and by changing the context you
can manipulate this start area, using code. Because the code uses a path
lookup, the same JSP fragment will work in all your localized sites.
In the code snippet in listing 1, the context is set first by use of a path in the
current library (“./mySite/mySiteArea”), and then the navigator
(“theNavigator”) from the library “theLibrary” is rendered.
Listing 1. Code for setting context and rendering navigator
<%@ page import="com.ibm.workplace.wcm.api.*" %>
<%@ taglib uri="/WEB-INF/tld/wcm.tld" prefix="wcm" %>
<wcm:initworkspace user="<%= request.getUserPrincipal() %>" />
<%
RenderingContext context =
(RenderingContext)request.getAttribute(Workspace.WCM_RENDERINGCONTEXT_KEY);
String currentLibrary = context.getLibrary().getName();
String navStart = currentLibrary+"/mySite/mySiteArea";
2 5
25. %>
<wcm:setExplicitContext path="<%=navStart%>"/>
<wcm:libraryComponent name="theNavigator" library="theLibrary" />
Localized menu components
Menus should mostly be able to use the “Current content site area” option
and include ancestors and descendents where appropriate, enabling you to
search the entire current site.
If a menu needs to select site areas specifically, then the menu cannot be
shared easily across locales. As for navigators, this means using the dot
notation to include the localized menu component, and design elements
would be shared wherever possible.
Another method of localizing a menu is to use a JSP fragment to render the
menu, allowing the list of site areas to be specified at render time. As the
paths in each locale are the same, the same JSP fragment can be used to
render a menu across multiple locales.
This code snippet in listing 2 shows how a menu (“theMenu”) from the
library “theLibrary” is set up to use a query string parameter to receive site
areas (“SiteAreas”) that are built using the current library name.
Listing 2. Code for setting up a menu from the library
<%@ page import="com.ibm.workplace.wcm.api.*, java.util.*"%>
<%@ taglib uri="/WEB-INF/tld/wcm.tld" prefix="wcm" %>
<wcm:initworkspace user="<%= request.getUserPrincipal() %>" />
<%
RenderingContext context =
(RenderingContext)request.getAttribute(Workspace.WCM_RENDERINGCONTEXT_KEY);
String currentPath = context.getPath();
String currentLibrary = context.getLibrary().getName();
Map myparams = new HashMap();
myparams.put("SiteAreas",
currentLibrary+"/mySite/mySiteArea1,"+currentLibrary+"/mySite/mySiteArea2")
;
%>
<wcm:setExplicitContext path="<%=currentPath%>"
requestParameters="<%=myparams%>"/>
<wcm:libraryComponent name="theMenu" library="theLibrary" />
Synchronizing components using workflow
You cannot synchronize components using the same automated process as
for content because the Web Content Management API does not provide
workflow methods for non-content items. Instead, you can set up simple
workflow processes using email notifications.
Given that (1) there are typically many times less components than content,
(2) a smaller set of users manage them, and (3) they are not updated as
often, this is not a serious limitation.
2 6
26. Localized site searching
The following steps are recommended for the searching of multi-locale sites.
1. Create a search collection for each locale specifying the appropriate
language (see figure 8).
Figure 8. Create search collection
2. Make each site searchable and select the search collection that has
been created for that locale (see figure 9).
Figure 9. Making each site searchable
3. Create a search component for each locale/library, selecting the relevant
search collection or using the Search and Browse portlet.
2 7
27. NOTE: If using a search component, use either the “Site / site area
elements” or “Dot notation” method described above to render the
component.
2 8
28. 8
Localized rendering
L ocalized rendering is used to ensure that the appropriately localized
content is displayed to site visitors. The two basic strategies from
which to choose are to do this automatically by trying to match the
user’s locale with the content locale, or to provide a navigation option
in the site to let users choose the locale for themselves. These two
strategies may also be used together in some cases.
Auto-localization
In auto-localization, there are several language versions of a page, and a
user is automatically redirected to one of them based on their locale. The
locale is determined by the following methods:
U R L
The URL may contain the locale, for example, ibm.com.au or ibm.co.uk
B R O W S E R P R E F E R E N C E
Browsers let you specify your language preferences. Language preference
information is then sent by the browser in the Accept-Language http header.
For example, Accept-Language: en-ca,en-us;q=0.7,en;q=0.3
Note: The Domain Locale Redirection sample demonstrates this
functionality at the domain level (for example, www.ibm.com).
P O R T A L
The portal determines the language for rendering the portal content by a
search process along the following sequence at log-in time:
1. If the user has logged in, the portal displays the preferred language
selected by the user.
2. If no preferred user language can be found, the portal looks for the
language defined in the user's browser. If the portal supports that
2 9
29. language, it displays the content in that language. If the browser has
more than one language defined, the portal uses the first language in
the list to display the content.
3. If no browser language can be found, for example, if the browser
used does not send a language, the portal resorts to its own default
language.
4. If the user has a portlet that does not support the language that was
determined by the previous steps, that portlet is shown in its own
default language.
L I M I T A T I O N S
Auto-localization is evidently a useful thing, but before implementing it
across the board, it is important to understand its limits. To illustrate these,
we use the example of a site, www.example.be, that offers its content in
Finnish, French, and German. It implements auto-localization and defaults
to Finnish for all pages. Our visitor, Sylvia, speaks Italian but is able to deal
with German. Several situations may arise:
1. Sylvia's browser is correctly configured, expressing preferences for
Italian first, German second. If Italian is not available at
www.example.be, the pages are returned in German, the visitor is
fairly happy, and all is well. This is what language negotiation is for!
2. Sylvia is a non-technical person who has never heard of HTTP
language negotiation and has never felt a need to alter the settings of
her browser. The browser is an Italian version which (correctly)
defaults to expressing a preference for Italian. Hitting
www.example.be, Italian is not available and the site-default Finnish
is returned, even though German is available. Bad.
3. Sylvia is not using her own browser; she's sitting in an Internet café
in Moscow. The browser is configured for (or defaulted to) Russian.
She gets Finnish again. Bad.
Despite its limitations, auto-localization is a useful function that is desirable
to implement in multilingual sites. However, the shortcomings must be
addressed. In short, it is important to provide means for visitors to override
the automatic choice of language when it is wrong. This means putting
some interface elements in the page that link to the other available
languages. These controls must, of course, be clearly visible and
understandable by a visitor who has no familiarity with the language of the
currently displayed page. Also, these controls should be implemented on all
pages and not just the home page.
User-selected localization
In user-selected localization, the user selects a language manually from a
link or selection list. The selection can then be stored in a cookie for
3 0
30. subsequent visits to the Web site. There are a couple of different options for
letting the user select the locale:
L O C A L E S E L E C T I O N P A G E
In this case, a launch page displays when a user first comes to the site that
shows what locales are available, and the user then selects the appropriate
one. The navigation device could be links, a drop-down list, a clickable map,
or some combination of these. Whatever device is used, the result is a
simple redirection to the home page of the selected locale site.
E Q U I V A L E N T P A G E N A V I G A T I O N
On every page in the site, navigation is displayed that lets the user see the
same page in a different locale. The navigation device in this case may be
links, maps, etc. In this case, you change locales by linking to the equivalent
page in another locale (that is, the content on the same relative path in
another library).
If your site supports only a handful of localized versions, it is probably better
to avoid using a pull-down menu and simply include links directly on the
page. This gives you more flexibility to use graphics to represent foreign
text, avoids the difficulty of finding a suitable non-linguistic label for the list,
and lets users recognize the presence of and link to a page much more
quickly.
The key advantage of using pull-downs is to fit the selection into a smaller
space. If your pull-down points to more than 20 other sites or pages, you
should consider whether it is usable for those Web users who must scroll to
the end of the list. If not, you may consider linking to a dedicated global
gateway page at the home-page level.
The menu options should be translated into the target language. Instead of
including a link on the pull-down menu to a translation that reads, for
example, "French," the link should read "Français"; and instead of a link to
an alternative country site like "Germany" the link should read
"Deutschland".
Note: The Servlet Render-time navigation and Portlet Render-time
navigation samples demonstrate this functionality.
Some suggested options
Depending on a site’s requirements, a combination of auto-localization and
user-selected localization may be the best option.
Here are some options combining the two approaches:
3 1
31. O P T I O N 1
When a user enters the site for the first time, automatically detect the user’s
language preference using one of the methods described in the auto-
localization section above.
Provide a manual option on every page for changing the language. If the
language is changed, store the selection in a cookie and use it when the
user returns to the site.
O P T I O N 2
When a user enters the site for the first time, default to the most common
language, for example, English.
Provide a manual option on every page for changing the language. If the
language is changed, store the selection in a cookie and use it when the
user returns to the site.
Encoding
Preferably you use UTF-8 (Unicode) as the encoding for your page since
this encoding supports all the characters you need. If you cannot use UTF-
8, then you should use escapes to represent characters that are not
supported by the encoding of your page. Since all content is stored by Web
Content Management in the JCR database with UTF-8 encoding, character
data is preserved.
Portal sites should use the encoding that is set up in the Portal
Administration section. A servlet-rendered site should use the encoding
specified within WebSphere Portal.
3 2
32. If a site must have more than one encoding, multiple WebSphere Portal /
WebSphere Application Servers will be required, each with different
encoding settings (see figure 10).
Figure 10. Multiple encodings
A gateway is then used to convert the encoding.
Font face considerations
When implementing a multi-locale site, it is worth considering what font to
use. There are a few font faces in Windows® that are installed automatically
and can show multilingual characters. One of the best font faces is Tahoma.
It is easy to read and contains all the Unicode characters.
3 3
33. Deployment
D eployment of multi-locale sites can be centralized, running out of
single environment, or decentralized, whereby locales are served
from different environments.
For decentralized deployments your choice of localized navigation will affect
how you need to deploy your content to these environments; that is,
whether you provide navigation between equivalents items or simply provide
up-front navigation to the appropriately localized site.
Note that neither the sample locale navigation code nor the sample locale
redirection code supports multiple domains. Multiple domain support is a
rudimentary extension in both cases.
Centralized deployment
In a centralized deployment all locales are served from the same
environment, and all your localized content is syndicated in. This is a simple
option that works in most cases and allows full use of hardware.
You will typically want to set up mappings to each locale home page, either
as domains or as paths. These mappings provide easily remembered URLs
for users to link to a localized version of your site.
P A T H S O P T I O N
Each path is mapped to the home page in a localized library, resulting in
URLs like http://mydomain/en, http://mydomain/es.
M U L T I P L E D O M A I N S O P T I O N
Each domain is mapped to the home page in a localized library, resulting in
simple URLs like http://mydomain.com, http://mydomain.com.es.
There are some advantages in using multiple domains, including support for
domain restrictions in search engines like Google™.
3 4
34. It is important to remember that, in a multiple-domain solution, your localized
navigation links should change the domain, not just the path. This means
that the link generation should be a fully qualified path, not a relative path
(see figure 11).
Figure 11. Centralized environment
Decentralized deployment
In this case, locales are served from separate environments, one per
environment, or potentially multiple locales per environment. This is typically
done to get the site “closer” to the customer for performance and support
reasons.
Multiple domains must be used, whereby each locale or combination of
locales is served from its own domain.
The main decision to make when implementing a decentralized deployment
is whether you want users to be able to switch between localized content on
an item-by-item basis, or whether you can simply ask them which locale
they want up front and take them to the home page for that locale.
This decision governs how you need to set up syndication; specifically,
whether all localized content is required in each environment, or whether
you can split the content and syndicate only the single locale (or
combination) appropriate for each environment.
3 5
35. I T E M - B Y - I T E M L O C A L I Z A T I O N N A V I G A T I O N
Support this feature in a decentralized environment means you must have
all the content in all locales deployed to every locale environment (see figure
12). The navigation code can then check which content is available before
Figure 12. Decentralized environment 1: Item-by-item locale
navigation
rendering links, and the user can navigate to that localized version without
losing their session.
Potentially, if this is an anonymous site, you could redirect to the localized
version on another server since you may not need to maintain sessions.
This requires fully qualified links to be generated (which the sample code
does not do, but which could be added easily).
L O C A L E H O M E P A G E N A V I G A T I O N
If your site simply needs a link going to the home page of each locale (rather
than an item-by-item navigation), just create some links in your site that
navigate to your other servers (see figure 13). The advantage of
implementing your site this way is that you do not need to deploy all content
to all servers; you only need the content for the locale you intend to serve
out of that environment (and, of course, any shared assets).
Note that the links to your other localizations (that is, to the appropriate
domain for each localization) would need to be hard-coded because the
Web Content Management system cannot generate these links
automatically for you.
3 6
36. Deployment best practices
Refer the Deployment section in the white paper, Best practices for using
IBM Workplace Web Content Management V6, for more information on
deployment of Web Content Management servers.
Figure 13. Decentralized environment 2: Home page navigation
3 7
37. 10
Administration
A though in many cases the number of languages or regions you
require for a site is fixed, you may need to roll out new locales as
your organization expands.
Rolling out a new site is a process you can simplify by using the API
features of Web Content Management. The basic process for rolling out a
new locale is:
1. Copy the base site
2. Modify structure / content accordingly
3. Translate as required
To copy the site, use the Web Content Management API to crawl the base
site and create the equivalent localized site. In that way, templates can be
mapped appropriately, components may be copied or shared appropriately,
etc.
The copy is now ready for its initial translation and a once-off user
acceptance test before being deployed and going into the day-to-day
maintenance that is enabled through automated processes.
You may want to temporarily disable the automated syncing of this new site
while it is going through its initial translation and testing phases.
3 8
38. 11
Sample code for authoring,
workflow, and rendering
T his white paper includes sample code available for download that
provides plug-ins for Web Content Management authoring, workflow,
and rendering. In order for the samples to work, the files shown in
table 3 below must be downloaded and installed, per the installation
and configuration steps.
Note that the performance of the sample code is a function of the number of
localized libraries and the content creation rate. If both the number of
localized libraries and the content creation rate is high, then you might need
to enhance the samples, for example, by caching the output of the authoring
time and rendering time samples, scheduling the workflow pollers to run
during off hours, etc.
Installation and configuration
R E Q U I R E D W E B C O N T E N T M A N A G E M E N T V E R S I O N
You must be running Web Content Management 6.0.1.2 or later for the
sample code to function.
Table 3. Download files
F I L E N A M E D E S C R I P T I O N
MLConfigurationLibrary.zip The configuration library that is to be
imported
MLAuthorTimeInfo_EditMode.jsp, Jsps for the Edit-time
MLAuthorTimeInfo_ReadMode.jsp, navigation/Creation sample
MLAuthorTimeInfo_Init.jsp
MLLocaleNavigator.jsp Jsp for the Servlet Render-time
navigation sample
3 9
39. MLPortalLocaleSwitcher.jsp Jsp for the Portlet Render-time
navigation sample
MLUtils.jsp Utility Jsp used by the edit-time and
render-time samples
MLServletHomePageRedirection.jsp Jsp for the Domain Locale
Redirection sample
wcm-ml-contextprocessor.jar Jar file for the Portlet Render-time
navigation sample
wcm-sample-workflowpolling.ear EAR file that contains the polling
framework and example pollers for
the Workflow Synchronization
samples
S E T U P T H E C O N F I G U R A T I O N L I B R A R Y
You must set up the configuration library before running any of the samples,
as follows:
1. Import the ML Configuration Library:
a. Unzip the MLConfigurationLibrary.zip files to a directory.
b. Import the MLConfiguration Web Content Management library.
See the Exporting and importing a Web content library section in
the InfoCenter for instructions on how to import a library.
c. Restart the WebSphere Portal server.
2. Modify the security of the MLConfiguration library as follows:
a. Create a group (such as “Locale Owners”) to house all users that
will own one or more locales (include the Base Locale Owner in
this group).
b. Assign “Locale Owners” and the Administrators group the
Contributor role on the library.
c. Assign Locale Owners the Editor role on the “Content” Item Type
in “Library Resources”.
d. Optional (but recommended), uncheck the Allow Inheritance
checkbox for all Item Types except “Content” and “Components”
(this hides all sections in the Authoring UI for the MLConfiguration
library from Locale Owners except “Content” and “Components”).
e. Assign the Administrators group the Administrator role for all Item
Types.
4 0
40. NOTE: See the Defining roles within a library section of the
InfoCenter for additional instructions on modifying roles.
3. Configure the authoring portlet so that the MLConfiguration library is
added to the library selection list.
4. Create the content representing the ML Configuration File:
a. From the Web Content Management Authoring portlet, navigate
to the MLConfiguration library and create a new piece of content
using the ConfigurationFileAT Authoring template.
b. Fill in the fields on the Configuration document as follows (see
figure 14):
i. Name: Leave the default value
ii. Display Title: Leave the default value
iii. Base Content Library: Enter the name of the Web Content
Management Library that will house content from the
default locale.
iv. Content Libraries: Enter the names of all Web Content
Management Libraries that will house content (including
the Base Content Library), separated by commas.
NOTE: The order in which libraries are entered here
affects the output of the render-time and edit-time
samples, so it’s recommended to place the Base Content
Library first then add the remaining libraries in the order in
which you wish them to be displayed.
v. Content Library Owners: For each library mentioned in the
Content Libraries, specify the email address of the user
who will be the owner for that library, placing each entry
on a new line.
Note that the MLConfiguration library must be syndicated to all staging and
production servers like any other library.
4 1
41. Figure 14. Example Configuration document
I N S T A L L T H E W O R K F L O W P O L L I N G A P P L I C A T I O N
The wcm-sample-workflowpolling.ear file must be installed if you want to run
any of the workflow polling samples.
1. Install the Workflow Polling Application:
a. Copy the wcm-sample-workflowpolling.ear file to a directory on
the server
b. Shutdown your WebSphere Portal server
c. Start the WebSphere Application Server, Server1
d. Open the WebSphere Application Server administration console.
Go to Applications > Install New Application
e. Click the Browse button and select the wcm-sample-
workflowpolling.ear file
4 2
42. f. Click Next three times
g. On the “Map modules to servers” screen, map the ear file to the
Portal server by selecting the checkbox next to the module, then
selecting the WebSphere Portal server in the list of servers, and
then clicking Apply and Next.
h. Click Next, and click Finish.
i. Click Save to Master Configuration and click Save.
2. Modify the Workflow Polling Application’s starting weight:
a. From the Applications view of the WebSphere Application Server
administration console, locate the “WCM Sample Workflow
Polling” application and click the link representing the
application’s name.
b. Set the Starting Weight property to 30 and click OK.
c. Click the Save link and click Save.
3. Start the WebSphere Portal Server to activate the application.
4. Optional: Activate Email Notifications for the workflow polling samples
a. From the Web Content Management Authoring portlet, open the
content called “ConfigurationFile” under the MLConfiguration
library
b. Click the Edit button.
c. Make the following changes to the General Workflow
Synchronization Settings section (see figure 15):
i. emailServer: Set this field to the name of your email server
ii. emailFromAddress: The email address entered here will
be used to set the ‘From’ address on all email
notifications. This field must be set to a valid email
address.
iii. authoringUIURL: This field is used to create links to
processed content items. It should be set to the URL of
your Authoring server, for example,
http://localhost:10045/wps/myportal/wcmAuthoring
4 3
43. Figure 15. Example configuration document, continued
d. To enable email notifications for the SyncUpdate Workflow polling
sample:
i. Set the SyncUpdatePoller.emailNotificationsEnabled field
in the SyncUpdate Workflow Synchronization Settings
section to true.
e. To enable email notifications for the ‘SyncPublish’ Workflow
polling sample:
i. Set the SyncPublishPoller.emailNotificationsEnabled field
in the SyncPublish Workflow Synchronization Settings
section to true.
f. To enable email notifications for the SyncExpire Workflow polling
sample:
4 4
44. i. Set the SyncExpirePoller.emailNotificationsEnabled field
in the SyncExpire Workflow Synchronization Settings
section to true.
g. To enable email notifications for the SyncDelete Workflow polling
sample (see figure 16):
i. Set the SyncDeletePoller.emailNotificationsEnabled field
in the SyncDelete Workflow Synchronization Settings
section to true.
Figure 16. Example configuration document, continued
Samples
E D I T - T I M E N A V I G A T I O N / C R E A T I O N S A M P L E
This sample provides a means to navigate between localizations of the
same item and to create new documents in the Localized libraries.
4 5
45. Follow these steps to install the sample:
1. Follow the steps in the Adding JSPs to the Local Rendering Portlet and
Adding JSPs to the Web Content Management Authoring UI Portlet
sections of the Appendix, to add the following JSPs to all authoring
nodes and any rendering nodes that will use inline-editing:
• MLAuthorTimeInfo_EditMode.jsp
• MLAuthorTimeInfo_ReadMode.jsp
• MLAuthorTimeInfo_Init.jsp
• MLUtils.jsp
NOTE: This process will need to be repeated whenever a fixpack is
applied.
2. For all authoring templates on which you want to enable the
Navigation/Creation links, add a text component called “ML Translations”
to the authoring template, with the following properties:
a. Set the Custom JSP field to the following:
readMode=MLAuthorTimeInfo_ReadMode.jsp,editMode=MLAuthorTimeInfo_EditMode.j
sp
TIP: Placing the new text component above any existing components
looks better.
3. Save the authoring template and re-apply it to all content that uses it,
ensuring the Add new elements option is selected.
How it works
Every time you open content with the Custom JSP on it, all libraries
configured in the ML Configuration file are searched for all matching
content. To be matching, it must be in the same site area and have the
same name (the display titles don’t have to match).
If a matching document is found, then you’ll receive a link to that document
(see figures 17 and 18). Clicking the link opens the document within the
Authoring portlet in read mode. The link displays Draft, Published, Expired,
Published with Draft, or Expired with Draft, as appropriate. If the existing
document is a link from the current document, then the text “Linked to this
document” will display.
Figure 17. Base Locale document with one localized Draft copy of document
4 6
46. Figure 18. Localized document with link to Base Locale published document
If no matching documents are found in any of the libraries and you have edit
access to the content and the field, then you’ll see some creation buttons. If
the content being viewed is in the Base Locale library, then the following
buttons display (see figure 19):
• Copy Base Locale as Draft: Uses the “Copy” Remote action to copy
the Base Locale document into the Localized library (under the
equivalent site area) as a draft document. If there is a workflow in the
Localized library with the same name as the workflow on the Base
Locale document, then the workflow will be automatically switched to
the Localized version.
• Link from Base Locale: Uses the new “Link” Remote action to place
a content link to the Base Locale document under the equivalent site
area in the Localized library.
Figure 19. No Localized documents exist (with edit access)
If the content being viewed is in a Localized library, then you’ll see the
following button (see figure 20):
• Copy This as Draft: Uses the new “Copy” Remote action to copy the
current document into another Localized library or Base Locale
library (under the equivalent site area) as a draft document.
Figure 20. No Base Locale document exists
If you don’t have edit access to the content or the custom field, then you’ll
see the display in figure 21.
Figure 21. No localized documents exist (without edit access)
4 7
47. U P D A T E N O T I F I C A T I O N S A M P L E
This sample uses the settings in the Workflow Synchronization section of
the ML Configuration file (that you created above) to automate the creation
of localized documents.
Follow these steps to use the sample:
1. Ensure the Workflow Polling Application has been installed.
2. Create a workflow stage called “SyncUpdate” or whatever name has
been configured in syncUpdatePoller.workflowStage in the ML
Configuration file.
3. Place this workflow stage after the approval stage.
The configuration settings and processed workflow stages for the “Update
Notification Sample” are not reloaded each time the sample is run; instead,
they are reloaded based on SettingReloadInterval. This value is set within
the General Workflow Syncronization Settings section of the ML
Configuration file, where the interval is the number of times that the sample
is run before checking for new settings.
If you do not plan to use the Update Notification Sample, then you should
follow the instructions in the Disabling a workflow poller section of the
Appendix to disable the MLSyncUpdate workflow poller.
How it works
When a document reaches the SyncUpdate workflow stage, the following
occurs:
• If one or more localized copies of the current document are found
that don’t have a corresponding “Draft” Base Locale document (in
any stage of the workflow), then all copies are moved to the next
workflow stage and a notification is sent to the Base Locale owner,
informing him that changes have occurred to Localized documents
without an associated change to the Base Locale document.
• If the Base Locale document is in an earlier stage of the workflow,
then nothing will happen.
• If, however, the Base Locale document is in the current stage or a
later stage, then each configured library that doesn’t already have a
draft document will be processed according to the SyncUpdate
Workflow Synchronization Settings within the ML Configuration file
and a notification will be sent to the all affected locale owners:
o If the library being processed contains an existing published
or expired document, then SyncUpdate Workflow
Synchronization Settings will be ignored, and a draft copy of
the existing document will be created.
4 8
48. o If the library being processed doesn’t contain an existing
published or expired document, then it will be processed as
follows, depending on its configured “Localization setting”:
Translate (the default): Copies the Base Locale
document into the localized library and restarts the
workflow of the copied item. If the localized library
contains a workflow with the same name as that used
by the Base Locale document, then the workflow on
the copied item will be changed to the identified
localized workflow.
DontTranslate: Creates a content link to the Base
Locale document in the localized library.
DontLocalize: Skips processing of the localized library
NOTE: If the destination site area does not exist in the
localized library, then the Translate and DontTranslate actions
will fail with an error.
Modifying the localization setting for a specific library
To modify the localization setting for a library, perform the following steps:
1. From the Web Content Management Authoring portlet, open the content
called “ConfigurationFile” under the MLConfiguration library
2. Click the Edit button.
3. Make the following changes to the SyncUpdate Workflow
Synchronization Settings section:
a. If there is an existing syncUpdatePoller.<LIBRARY_NAME>
.localizationSetting field (where <LIBRARY_NAME> is the name
of your localized library), then set its value to the required
localization setting.
b. If there isn’t an existing syncUpdatePoller.<LIBRARY_NAME>
.localizationSetting field (where <LIBRARY_NAME> is the name
of your localized library), then create a new field at the bottom of
the SyncUpdate Poller Preferences section named:
syncUpdatePoller.<LIBRARY_NAME>.localizationSetting=<LOCALIZATION_SETTING>
where:
• <LIBRARY_NAME> is the name of your localized library
• <LOCALIZATION_SETTING> is the required localized setting
for example, syncUpdatePoller.MyLibrary.localizationSetting=
DontTranslate
4 9
49. P U B L I S H I N G S Y N C H R O N I Z A T I O N S A M P L E
This sample ensures that the base item and any draft Localized items are
published at the same time.
Follow these steps to install and use the sample:
1. Ensure the Workflow Polling Application has been installed.
2. Create a workflow stage called “SyncPublish” or whatever name has
been configured in syncPublishPoller.workflowStage in the ML
Configuration file.
3. Place this workflow stage just before the publish stage.
The configuration settings and processed workflow stages for the Publishing
Synchronization Sample are not reloaded each time the sample is run;
instead, they are reloaded based on the SettingReloadInterval. This is set
within the General Workflow Syncronization Settings section of the ML
Configuration file, where the interval is the number of times that the sample
is run before checking for new settings.
If you do not plan to use the Publishing Synchronization Sample, then you
should follow the instructions in the Disabling a workflow poller section of the
Appendix to disable the MLSyncPublish workflow poller.
How it works
When a document reaches the SyncPublish workflow stage, the following
occurs:
• If any draft localized copies of the current document aren’t in the
SyncPublish workflow stage, then nothing will happen.
• If all draft localized copies of the current document are in the
SyncPublish workflow stage, then the current document and its
copies will be moved to the next workflow stage and a notification will
be sent to the all affected locale owners.
NOTE 1: As this sample processes only existing Draft localized
copies of the current document, it’s not necessary for every localized
library to have a draft copy present.
NOTE 2: All required localized copies are assumed to have been
created by the Sync Update workflow polling sample
E X P I R Y S Y N C H R O N I Z A T I O N S A M P L E
This sample ensures that the base item and any published localized items
are expired at the same time.
5 0
50. Follow the steps below to use the sample:
1. Ensure the Workflow polling application has been installed.
2. Create a workflow action called “SyncExpire” or whatever name has
been configured in syncExpirePoller.workflowStage in the ML
Configuration file.
3. Place this workflow stage just before the expire stage.
The configuration settings and processed workflow stages for the Expiry
Synchronization Sample are not reloaded each time the sample is run;
instead, they are reloaded based on the SettingReloadInterval. This is set
within the General Workflow Syncronization Settings section of the ML
Configuration file, where the interval is the number of times that the sample
is run before checking for new settings.
If you do not plan to use the Expiry Synchronization Sample, then you
should follow the instructions in the Disabling a workflow poller section of the
Appendix to disable the MLSyncExpire workflow poller.
How it works
When a document reaches the SyncExpire workflow stage, the following
occurs:
• If any published localized copies of the current document aren’t in the
SyncExpire workflow stage, then nothing will happen.
• If all published localized copies of the current document are in the
SyncExpire workflow stage, then the current document and its copies
will be moved to the next workflow stage and a notification will be
sent to the all affected locale owners.
D E L E T I O N S Y N C H R O N I Z A T I O N S A M P L E
This sample ensures that the base item and any draft localized items are
deleted at the same time.
Follow the steps below to use the sample:
1. Ensure the Workflow Polling Application has been installed.
2. Create a workflow action called SyncDelete or whatever name has been
configured in syncDeletePoller.workflowStage in the ML Configuration
file.
3. Place this workflow stage at the end of your workflow.
The configuration settings and processed workflow stages for the Deletion
Synchronization Sample are not reloaded each time the sample is run;
5 1
51. instead, they are reloaded based on the SettingReloadInterval. This is set
within the General Workflow Syncronization Settings section of the ML
Configuration file, where the interval is the number of times that the sample
is run before checking for new settings.
If you do not plan to use the Deletion Synchronization Sample, then you
should follow the instructions in the Disabling a workflow poller section of the
Appendix to disable the MLSyncDelete workflow poller.
How it works
When a document reaches the SyncDelete workflow stage, the following
occurs:
• If there is a Base Locale copy of the current document and it’s not in
the SyncDelete workflow stage, then a Deletion Request email will
be sent to the Base Locale owner informing him that one or more
localized copies are to be removed.
• If there isn’t a Base Locale copy of the current document or it’s in the
SyncDelete workflow stage, then all available draft and published
localized copies will be removed and a notification sent to all
localized library owners, regardless of the workflow stage they are in.
S E R V L E T R E N D E R - T I M E N A V I G A T I O N S A M P L E
This sample JSP provides navigation between equivalent published content
in different locales from within a presentation template at rendering time.
Follow these steps to install the sample:
1. Follow the steps in the Adding JSPs to the Local Rendering Portlet and
Adding JSPs to the Web Content Management EAR File sections of the
Appendix, to add the following JSPs to all authoring nodes and
rendering nodes:
• MLLocaleNavigator.jsp
• MLUtils.jsp
NOTE: You will need to repeat this process whenever a fixpack is
applied.
2. For all content that is enabled, the localized rendering links add the JSP
Component “MLConfiguration/JSP - ML Locale Nav” to either the
associated presentation template or as a reference within a Rich Text
Editor or other field, for example, <Component
name="MLConfiguration/JSP - ML Locale Nav"/>
5 2
52. How it works
Every time you render a content item with the “JSP - ML Locale Nav” JSP
Component on it, all libraries configured in the ML Configuration file are
searched for all matching content.
To be matching, the content must reside under an equivalent site path; that
is, the site, site areas, and content must all have the same name (though
the display titles can be different).
For each document found, a link is created (using the locale of library in
which the matched content was found, but displayed in the current user’s
language) to navigate the browser to that document (see figure 22).
Although this sample works for both servlet and portlet rendering, for portlet
rendering it causes only the current portlet to update and thus is not
applicable in some cases.
Figure 22. Rendering component shown in right column
P O R T L E T R E N D E R - T I M E N A V I G A T I O N S A M P L E
This sample modifies the portal locale and allows the Local Rendering
portlet to become locale aware and thus automatically switch to an
equivalent object when the locale changes.
Follow these steps to install the sample:
1. Follow the steps in the Adding JSPs to the Local Rendering portlet
section of the Appendix, to add the following JSPs to all authoring nodes
and rendering nodes:
• MLPortalLocaleSwitcher.jsp
• MLUtils.jsp
NOTE: You must repeat this process whenever a fixpack is applied.
5 3
53. 2. Copy the following JAR file to the <WPS_ROOT>wcmsharedapp
directory for all authoring and rendering nodes:
• wcm-ml-contextprocessor.jar
3. Either integrate the MLPortalLocaleSwitcher.jsp into your portal theme or
place a Local Rendering portlet on the page configured to show the JSP
- ML Portal Locale Switcher Library Component in the MLConfiguration
Library.
4. Add the following property to the configuration of the Web Content
Viewer / Local Rendering portlet using the WebSphere Portal
Administration console:
• ContextProcessorClass
=com.ibm.workplace.wcm.sample.contextprocessor.MLContextProc
essor
How it works
The ContextProcessorClass setting tells the Local Rendering portlet to call
the specified class before rendering each item, and the
MLContextProcessor class checks whether the locale changed. If the locale
has changed, then it checks whether there is an equivalent item in the new
locale and, if so, updates the portlet’s runtime configuration to tell the portlet
to show the localized item.
If the Local Rendering portlet has its presentation template overridden via
the configuration, then a localized presentation template is also searched for
and used, if available.
The MLPortalLocaleSwitcher.jsp provides the ability to switch the
WebSphere Portal locale by first detecting the current locale and then using
the Portal URL API to create links to switch the locale to other available
locales, per the list of configured libraries in the ML Configuration file.
NOTE: This sample works in the Local Rendering portlet only.
D O M A I N L O C A L E R E D I R E C T I O N S A M P L E
This sample JSP redirects the main domain (for example, www.ibm.com) to
one of the set of allowable locales (for example, www.ibm.com/en) based
on the current user’s locale settings.
Follow these steps to install the sample:
1. Customize the MLServletHomePageRedirection.jsp file as follows:
a. Comment out the lines in the getAvailableLocalesList method,
representing those locales that won’t be supported
5 4
54. b. Optional: Change s_defaultLocale to match the required default
locale
2. Copy MLServletHomePageRedirection.jsp to the following location on all
rendering nodes:
<WAS_PROFILE_ROOT>installedApps<HOST>wcm.earilwwcm.
warjsphtml
5. Add the following text to the end of the IHS/Apache Web Server
configuration file:
LoadModule rewrite_module modules/mod_rewrite.so
RewriteEngine on
RewriteRule ^/$ /wps/wcm/jsp/html/MLServletHomePageRedirection.jsp [PT]
6. For each locale in the s_availableLocales list, add the following
additional text to the IHS/Apache Web Server configuration file (after the
entries added above:
RewriteRule ^/<LOCALE>$ /wps/wcm/connect/<LIBRARY>/<SITE> [PT]
where:
• <LOCALE> is the string representation of the corresponding
Java Locale object (for example, “fi” for Finnish and “pt_BR” for
Brazilian Portuguese),
• <LIBRARY> is the Web Content Management Library associated
with the locale, and
• <SITE> is the main Web Content Management site for the
specified library; for example, RewriteRule ^/en$
/wps/wcm/connect/english/Internet [PT]
NOTE: Do not map any of the locale redirections to the main domain as
this causes an infinite loop.
How it works
Every time you request the top-level domain (for example, www.ibm.com),
the MLServletHomePageRedirection.jsp runs and looks for the first match of
either the current user’s locale, or the ordered list of preferred languages set
in the browser, against the list of available locales as defined in the JSP.
The JSP then redirects back to the top-level domain plus the available
locale, where the Web server then runs the secondary redirections set up in
the Web server to redirect to the correct Web Content Management content
based on that locale.
Although this sample is primarly designed for servlet rendering, it could be
used with WebSphere Portal if you wanted to render different locales from
different servers.
5 5
55. 12
Where to go from here
T he framework outlined in this document is just the beginning; within
its basic outline there are many points of extensibility where you may
enhance the solution to suit your specific requirements. Some
examples are outlined below.
Locale owner decision points
Allow locale owners to decide to Copy, Link, or Ignore base items on a per-
item basis:
Using a new workflow stage that is routed to the locale owners
(perhaps using the parallel approval function)
Using a custom form component to provide an interface for soliciting
and recording each locale owner’s decision
Another workflow stage may then use the locale owner’s information
to create, update, delete, etc. the localized items
Per-locale configuration
Extend the configuration to be per locale:
Perhaps by providing an interface for locale owners to configure their
locale, including which site to base from, which site areas to copy vs.
link, which site areas to ignore, whether to sync publishing or not, etc.
You could build this configuration screen by using a special “library
configuration” Authoring template, and the content would then be
stored in a hidden “Locale Admin” site area (this is how the sample
code’s configuration is stored)
5 6