Custom Localization of Interaction Workspace

Introduction

The objective of this document is to provide guidelines to Genesys customers that would like to leverage localization capabilities of Interaction Workspace to build their own localization of the product, either by translating in a brand new language, or by modifying the terms used in out-of-the-box product localization. Legal Notice: Customer enabled language translation functionality is provided on an as-is basis for internal use only. Outside distribution of this functionality and/or any translation(s) created using such functionality is not permitted except under a separate agreement negotiated with Genesys specifically for the purpose of distributing Genesys-related translations.

General Principles of Localization in Interaction Workspace

Definition of the Language Pack

A Language Pack is a set of XML files that define the string that is used to display the Interaction Workspace User Interface in a given language. The language packs are stored in a directory named Languages that is located at the same level as the Interaction Workspace executable (actual directory structure might vary depending on the installation mode that was used). This directory contains a set of XML dictionary files for one or several languages. The string-definitions of a specific language are the compilation of keys that are declared in the set of XML files that have the same language-code/country-code extension (for example: en-US). Language codes are based on ISO 639-1, and Country codes are based on ISO 3166-1. The file name specifies the language in the following format: module_name.language_code-country_code.xml (for example: Genesyslab.Desktop.Modules.Core.en-US.xml)

Description of the content of a Language Pack

The table Interaction Workspace Language Pack Description displays the content of the out-of-the-box Interaction Workspace Language Pack for English-US.

Interaction Workspace Language Pack Description

Dictionary File Name	Privileges that control the use of the dictionary file	Notes
Genesyslab.Desktop.Modules.Contacts.en-US.xml	InteractionWorkspace.Contacts.*
Genesyslab.Desktop.Modules.Core.en-US.xml	Any	Core dictionary
Genesyslab.Desktop.Modules.OpenMedia.en-US.xml	InteractionWorkspace.Email.* InteractionWorkspace.Chat.* InteractionWorkspace.SMS.* InteractionWorkspace.WorkItem.* InteractionWorkspace.Workbins.*
Genesyslab.Desktop.Modules.Outbound.en-US.xml	InteractionWorkspace.Outbound.*
Genesyslab.Desktop.Modules.SIPEndpointCommunication.en-US.xml	InteractionWorkspace.SIP.*
Genesyslab.Desktop.Modules.StandardResponse.en-US.xml	InteractionWorkspace.SRL.*
Genesyslab.Desktop.Modules.Statistics.en-US.xml	InteractionWorkspace.ObjectStatistics.* InteractionWorkspace.GadgetStatistics.* InteractionWorkspace.KPI.*
Genesyslab.Desktop.Modules.TeamCommunicator.en-US.xml	InteractionWorkspace.TeamCommunicator.*
Genesyslab.Desktop.Modules.Voice.en-US.xml	InteractionWorkspace.Voice.* InteractionWorkspace.IM.*
Genesyslab.Desktop.Modules.Windows.en-US.xml	Any	Core dictionary

Depending on the Privileges that you assign to agents, you can avoid translating the dictionary files that correspond to modules that you have not installed. This reduces the effort of building your language pack.

Adding a new language

Goal

Deliver to agents a translation of Interaction Workspace application that is not yet available from Genesys.

Procedures

Creating a new Language Pack

Use the following steps to create a new language pack for Interaction Workspace.

1. Duplicate all of the XML Dictionary files of the existing language pack that you want to use as a reference (for example, English-US) and rename them by using the language and country codes of the new language.
2. Edit each dictionary file of the duplicated file set and translate to the new language the text that is contained in the following attributes: Name, String, Header, ToolTip, Text, Content, Title, ToolTipStatus, Watermark, Error, and ActionButtonToolTip
   • Translation of strings that contain the underscore character "_" must also contain an underscored character. These strings are represented as an Access Key in the User Interface (they are displayed as underlined when the agent presses the ALT key to directly access the control)
   • Translation of strings that contain placeholder character sequences such as {<digit>} (for example {0}) must also contain those character sequences.
   • Keys that are surrounded by the '<!--' and '-->' strings do not require translation
3. Once all the keys are translated, copy and paste the new XML file set for the new language into the Languages directory.

Deploying the new Language Pack

You cannot modify the Language Pack IP to deploy the custom language using the same out-of-the-box method that you use for Genesys-distributed language packs. To deploy in a custom language, you must build a combined package, using both the out-of-the-box Interaction Workspace files, as well as a custom Language Pack that you create.

Direct installation on Workstation

Add the new Language Pack file into the structure of an existing deployment so that the structure matches the following example:

[distribution_root]

*.dlls
interactionworkspace.exe
Languages

*.en-US.xml [out-of-the-box language pack]
*.<new_language_code>-< new_country_code>.xml [custom language pack]

Miscellaneous out-of-the-box directories and files

Installation through ClickOnce

Copy the files of the new Language Pack into the directory structure that was generated when Interaction Workspace was installed in "centralized deployment mode". The directory structure must match the following example:

[distribution_root]

*.dlls
interactionworkspace.exe
Languages

*.en-US.xml [out-of-the-box language pack]
*.<new_language_code>-< new_country_code>.xml [custom language pack]

Miscellaneous out-of-the-box directories and files
InteractionWorkspaceDeploymentManager

interactionworkspacedeploymentmanager.exe
Misc out-of-the-box deployment manager files

Execute Interaction Workspace Deployment Manager and follow the steps to deploy Interaction Workspace by using the Wizard interface.

Note: If you have already generated a ClickOnce package that did not contain the new Language Pack files, you must follow the following steps and redeploy Interaction Workspace.

1. In the "Package Information" step, check the Add custom files box.
2. Click Next.
3. Select all of the files (InteractionWorkspace\Languages\*.<new_language_code>-< new_country_code>.xml) of the new Language Pack in addition to you regular custom files, if any.
4. Finalize the execution of the wizard

Using the New Language Pack

Follow these steps to start Interaction Workspace and set it to start in your new language by default:

1. Restart the updated distribution of Interaction Workspace (from direct installation or ClickOnce).<liL
2. The Login window opens and displays a drop-down list that contains the original language(s) as well as the new language that you added.
3. Select an alternative language immediately to change the display to the new language. All windows that are subsequently opened are also displayed in the new language.

The Logic of Language Selection at Login Time

Language recognition works in the following way:

• The Languages directory contains a set of XML dictionary files for one or several languages. The file name reflect the language:

module_name.language_code-country_code.xml’ (for example: Genesyslab.Desktop.Modules.Core.en-US.xml)

• If at least one language XML file has a particular language/country extension (For example: fr-FR), the corresponding locale is considered available at run-time.
• All available languages (if number of languages is greater than or equal to 2) are presented in a combo-box on the first login page.
• The default selection in the combo-box is set by using the following logic:
  • If the current user workstation locale (language and country) is part of the available languages, then the default value is set to the user locale
  • If the current user workstation locale (language and country) is not part of the available languages, Interaction Workspace searches for an available language that has the language code in common. For example, if fr-FR is available but the user locale is fr-CA, then the default language is fr-FR
  • If no language or country code can be matched, then the default language is set to English-US
• The agent can select manually another language from the list of available languages.
• After the initial login, the language that was used during the previous session is automatically restored as the default language. It is always possible for the agent to select another language.

Notes and Recommendations:

• Some strings in the User Interface might be displayed in the original language after the new language is selected even if all keys that are contained in the dictionary files have been translated. The reason for this is that some strings come from the configuration layer and are not pre-configured in the dictionary file.
• Editing the EnglishName, CultureName, and Culture XML headers as shown here is recommended but not mandatory:

<Dictionary EnglishName="French" CultureName="Canada" Culture=" fr-CA ">

• Right-to-left reading languages, such as Arabic and Hebrew, are not supported.
• Carefully encode the dictionary files that you create to ensure that there is no data loss. Genesys recommends that you save your XML file in UTF8 format.

Customizing the Wording of an Existing Language

Goal

Replace the wording of an out-of-the-box Interaction Workspace string with a string that more closely matches your business context.

Procedure

Use the following steps to create a new language pack for Interaction Workspace that has the same name as an existing Interaction Workspace language pack.

1. Create a new XML Dictionary file that uses the same naming policy as the out-of-the-box Interaction Workspace language files: custom _name.language_code-country_code.xml
2. Set the following XML header to specify that it is a custom dictionary to ensure that the definitions in this file override the default strings of this language: <Dictionary CustomDictionary="true">
3. Identify the key that you want to customize in one of the original files of the given language and replicate it in your new custom file.
   

   For example: <Value Id="State.Agent.Ready" Text="Ready" String="Ready"/>

4. Modify the text that is contained in the attributes of the key that was copied into the custom file. You can modify the types of the following attributes:
   
   • Name
   • String
   • Header
   • ToolTip
   • Text
   • Content
   • Title
   • ToolTipStatus
   • Watermark
   • Error
   • ActionButtonToolTip
5. Copy the resulting XML Dictionary file into the Languages directory.
6. Restart Interaction Workspace.

Notes and Recommendations:

• The only mandatory XML header for a custom file is CustomDictionary.
• The following XML headers are optional: EnglishName, CultureName, and Culture. For example: <Dictionary EnglishName="English" CultureName="English" Culture="en-US" CustomDictionary="true">.

Potential Errors and Consequences

The table Interaction Workspace Language Errors displays the most common errors that you might encounter when you create custom language packs.

Interaction Workspace Language Errors

Error Message	Consequence
A particular key is not present in any of the files of the new language	The interface will display the value of the default language (en-US).
Malformed XML formatting	It is not possible to switch to the new language.
Translated string is very long	String might appear truncated in the application when the new language is selected.
Keys surrounded by '<!--' and '-->' are translated	Content is not displayed in the interface.
The characters "{0}" are in the original file but are missing in the translation	Some strings are not displayed.

Upgrade Considerations

When a new version of Interaction Workspace is released, the default Language Pack might be updated. An update of the Language Pack might consist of the following changes:

• New keys added to an existing dictionary file
• New dictionary file(s) that correspond to new a privilege(s)
• Removal of a key that existed in a previous version of the product
• Change of a string(s) that is associated with a key that existed in previous version of the product
• Movement of a key that existed in previous version of the product from one dictionary file to another

To avoid errors, an upgrade of custom language packs must be planned to ensure that the Interaction Workspace User Interface displays correctly in the new version.

Localizing Custom Content in Interaction Workspace

Refer to the Workspace Developer's Guide for information about localizing Interaction Workspace.