Adding a New Language in Convergence
You can customize Convergence to make it available in multiple languages in addition to those supported by default. Moreover, any individual domain can be customized to display a particular language to users in that domain.
This article includes the following topics:
Overview of Tasks
To add a new language in Convergence, you must perform these tasks:
- Add your own resources for the new language. The resource file contains the localized text for labels, names, and other text that appears in the UI.
- Enable end users to select the language by adding it to the drop-down list of languages displayed in the Global Options menu.
To create custom l10n (i18n) resources, you must use the dojo i18n directory infrastructure. Place your custom resource file in the iwc_static/c11n/<domain>/nls subdirectory. Domain is the domain where the customized languages will be available. Use the allDomain directory to apply to all domains in your deployment.
To Add a New Language in Convergence
The following steps outline how to customize the UI to support and display a new language:
1. Enable customization in the Convergence Server.
Before you can customize the UI, the Convergence Server must be enabled for customization. Use the command-line utility, iwcadmin, to set the client.enablecustomization parameter to true. For example:
./iwcadmin -u <uid> -W <password file> -p <port number> -o client.enablecustomization -v true
2. Create the customization directory, /c11n.
All customizations must be located under this directory.
/iwc_static/c11n
3. Edit the configuration file, config.js, by setting the i18nEnabled flag to true:
/c11n/config.js
You can create this file by copying an example of the config.js file from the sample customization directory:
/iwc_static/c11n_sample
In the config.js configuration file, set the i18nEnabled flag to true.
4. Create an nls/new language subdirectory for the l10n module:
iwc_static/c11n/<domain>/nls/<new language>
where domain is the name of the domain in which the new language will be available
and new language is the subdirectory in which the new language's resource file is located. For example:
iwc_static/c11n/allDomain/nls/ru
5. Create a default resource file named resources.js.
iwc_static/c11n/<domain>/nls/<new language>/resources.js
For example, to add an l10n resource file that adds Russian to all domains, you could create this path:
iwc_static/c11n/allDomain/nls/ru/resources.js
Since a new language requires the entire resource file translation, you can copy the Convergence English resource file (iwc_static/js/iwc/i18n/nls/resource.js) to begin with. Note that each language added to each domain would have its own l10n resources file (resources.js). Depending on the end-user's language locale, Convergence loads that locale's resources file.
Note: the directory structure should be as shown in the following example. In this example, the language "ru" is added to the allDomain directory. (Thus, it applies to all domains.)
iwc_static/c11n/allDomain/nls/ iwc_static/c11n/allDomain/nls/resources.js (Default resources.js file for all customized languages in this domain.) iwc_static/c11n/allDomain/nls/ru/ iwc_static/c11n/allDomain/nls/ru/resources.js (This resources.js file contains the localization required for the newly added language, "ru".)
You can also create this file by copying an example of the resources.js file from the sample customization directory, /iwc_static/c11n_sample.
Workaround to Add a New Language That Does Not Currently Exist in the Dojo Toolkit
Use this procedure to add a new language to Convergence that either does not currently exist in the Dojo toolkit or is not complete, as is the case with calendar data formats for Russian (ru). You basically follow the instructions in To Add a New Language in Convergence but with the following additions.
- Extract the sample code in the nls.tar file.
Note
This sample source will be included in a future update to Convergence. For now, use the attached sample code.You should see two files, resources.js and gregorian.js. Place them in the nls\ru directory.
- Change the customize.js file.
Uncomment the dojo.require("c11n.allDomain.js.widget.OptionsViewerGlobalGeneral"); and add the following lines:// adding new language will need localization of dojo calendar string dojo["requireLocalization"]("c11n.allDomain", "gregorian"); dojo.date.locale.addCustomFormats("c11n.allDomain","gregorian"); - Change the English and Russian strings to the desired language.
- Make sure you also have a gregorian.js file in the nls directory itself. Otherwise, Convergence hangs for the default languages. The file can be something like the following:
({ }) - Make sure you also have a resources.js file in the nls directory (see bug 6745757). For example:
{ last: "" } - You need to have an extra file, /docroot/iwc_static/c11n/allDomain/js/widget/CalendarMonthly.js. This file gets the names of the days also in the month view. For example:
dojo.provide("c11n.allDomain.js.widget.CalendarMonthly"); dojo.require("iwc.widget.CalendarMonthly"); dojo.declare("iwc.widget.CalendarMonthly", iwc.widget.CalendarMonthly, { postCreate: function() { this.dayNames = dojo.date.locale.getNames('days', "wide", 'standAlone', this.lang); this.inherited(arguments); }, last: "" } ); - Make sure the above file is called from /docroot/iwc_static/c11n/allDomain/js/customize.js, for example, at the end:
dojo.require("c11n.allDomain.js.widget.CalendarMonthly"); // adding new language will need localization of dojo calendar string dojo["requireLocalization"]("c11n.allDomain", "gregorian"); dojo.date.locale.addCustomFormats("c11n.allDomain","gregorian"); - Restart Application Server. For example:
# /opt/SUNWappserver/bin/asadmin stop-domain domain1 Domain domain1 stopped. # /opt/SUNWappserver/bin/asadmin start-domain domain1 Starting Domain domain1, please wait. Log redirected to /opt/SUNWappserver/domains/domain1/logs/server.log. Please enter the admin user name>admin Please enter the admin password>adminpass Please enter the master password>adminpass Redirecting output to /opt/SUNWappserver/domains/domain1/logs/server.log Domain domain1 started.
- Restart your browser, clearing its cache. Then log in to Convergence.
Sample Custom l10n Resource File
The following example shows a sample resources.js file which shows a few labels localized into Russian:
{
compose_tab: "Собрать",
}
The Convergence i18n service uses dojo l10n modules. For details about customizing languages, consult the dojo l10n documentation.
To Add a Label for the New Language to the Global Options Language Menu
Once you have created a localized version of the resources file, you need to make the new language available to end users. Users can select a language from the Options menu by selecting Global, then General.
The Global Options - General panel displays the languages supported by default in a drop-down list. You can add the new language to this list by creating and editing the OptionsViewerGlobalGeneral.js widget.
Take these steps:
1. Enable customization in the Convergence Server.
Before you can customize the UI, the Convergence Server must be enabled for customization. Use the command-line utility, iwcadmin, to set the client.enablecustomization parameter to true. For example:
./iwcadmin -u <uid> -W <password file> -p <port number> -o client.enablecustomization -v true
2. Set the jsEnabled flag to true in the config.js file.
/c11n/config.js
(If you have not already done so, you must create the /c11n directory and config.js file. For details, see Steps 2 and 3 in To Add a New Language in Convergence.)
3. Create the following subdirectory under the customization (c11n) directory:
iwc_static/c11n/<domain>/js
where domain is the domain in which the customized language will be available.
4. Create a customize.js file, as follows:
iwc_static/c11n/<domain>/js/customize.js
You can create this file by copying an example of the customize.js file from the sample customization directory, /iwc_static/c11n_sample. For example, you could copy the file from
iwc_static/c11n_sample/allDomain/js
At runtime, this file is responsible for loading the javascript customizations (the custom widget files) in this subdirectory. For details, see How the customize.js File Manages Customized Widgets.
5. In the customize.js file, uncomment the following line:
dojo.require("c11n.allDomain.js.widget.OptionsViewerGlobalGeneral");
6. Create a subdirectory to contain the custom widgets:
iwc_static/c11n/<domain>/js/widget
7. Copy the sample version of the OptionsViewerGlobalGeneral.js file from the sample customization directory to your live customization directory:
Copy from
iwc_static/c11n_sample/allDomain/js/widget/OptionsViewerGlobalGeneral.js
to
iwc_static/c11n/<domain>/js/widget/OptionsViewerGlobalGeneral.js
For example, the following directory structure is created when you customize the OptionsViewerGlobalGeneral.js widget in the allDomain directory:
/c11n/config.js /c11n/allDomain/js/customize.js /c11n/allDomain/js/widget/OptionsViewerGlobalGeneral.js
8. Edit the OptionsViewerGlobalGeneral.js file, adding your language.
The sample file adds Russian and Thai, as follows:
dojo.provide("c11n.allDomain.js.widget.OptionsViewerGlobalGeneral");
dojo.require("iwc.widget.OptionsViewerGlobalGeneral");
dojo.declare("iwc.widget.OptionsViewerGlobalGeneral",
iwc.widget.OptionsViewerGlobalGeneral,
{
buildRendering: function() {
this.inherited(arguments);
// add your new languages here
// value: language code - e.g., "en", "zh-TW"
// label: display name, use UTF-8 for double bytes
this.language.addChild({value: "ru", label: "Russian"});
this.language.addChild({value: "th", label: "Thai"});
},
last: ""
}
);
In the line this.language.addChild:
- The value: identifies the language code. This should be the l10n directory you created for your language. For example, the Russian example uses ru.
- The label: identifies the display name of the language. This name appears in the drop-down list of languages in the Global Options - General panel. For example, "Russian."
8a. Edit "ru" and "Russian", replacing them with your language directory and name. Use UTF-8 for double-byte characters.
8b. Delete the second this.language.addChild line, which adds Thai.
(If you are adding two new languages, edit the Thai values, replacing them with your second custom language.)
To Add a Label for the New Language to the Convergence Login Page
The languages supported in Convergence by default are shown on the Convergence login page.
For this release of Convergence, to add the new language to this list, you must edit the login html file, login.html.
The login.html file is a static component downloaded to the user's browser. Unlike a dojo widget, the html file does not dynamically extend the base dojo code. Moreover, login.html is one of the layout files in the base code. It cannot be loaded from the c11n customization directory.
Therefore, editing the login.html file differs significantly from extending a widget to customize the UI.
The following figure shows the default Convergence login page. The supported languages are listed at the bottom of the page.
Figure 1. Convergence Login Page with List of Supported Languages
To add a new label to the login page:
- Navigate to
iwc_static/layout/login.html
- Add your language to the list of languages on the html page. Use UTF-8 for double-byte characters.
Because this task involves editing part of the base file layout, your customizations will not be preserved when you upgrade Convergence. After an upgrade, the new version of login.html would replace your customized version.
To preserve your customization, you can physically copy login.html to another location. After an upgrade, you can copy your customized version back to the iwc_static/layout/ directory.
However, this strategy would overwrite the upgraded version of the file with your existing file. To preserve both the upgraded components in the file and your customization, you would have to merge your custom html markup, which adds the custom language to the list, with the new version of the file.
Sample Directory Structure for i18n
The following example illustrates the directory structure of i18n in the allDomain directory:
/c11n/config.js /c11n/allDomain/nls/resources.js /c11n/allDomain/nls/<lang>/resources.js
In the preceding example, the variable <lang> is one of the supported languages.
Comments (18)
Feb 27, 2008
Sarma.Vempati@Sun.COM says:
Is /c11n/defaultDomain/i18n/nls/resources.js is to be created? how? Unclear wha...Is /c11n/defaultDomain/i18n/nls/resources.js is to be created? how?
Unclear what this implies:
"Communication Center sets up the l10n module for loading codes to load each domain's l10n file."
Apr 28, 2008
HarischandraPrasad says:
The location of the resources.js was mentioned unclear/wrong. I have created res...The location of the resources.js was mentioned unclear/wrong. I have created resources.js file under .../defaultDomain/... but not working. So, I have placed the file under ../c11n/allDomain/nls/te/resources.js and is working fine.
It would be nice if we can tell how to add new language and corresponding locale code in the drop down list in Options -> General page.
For example, I have localized UI to new language, Telugu. Now how to set the language to "Telugu" for a user from Options -> General preferences page?
Apr 29, 2008
HarischandraPrasad says:
Adding new locale is working fine. But one concern here is, if I disable client....Adding new locale is working fine. But one concern here is, if I disable client.enablecustomization its not working. Technically this is perfectly fine as this entire process is under customization. But usually the deployments may have so many languages installed in one deployment. For example in INDIA I have seen few of our webmail customers, they have more than 10 indian locales. So, few people may have enabled customization or disabled depend on their current requirement. But if he disables customization, he cannot see even the UI in his own locale. Is this is acceptable? Do we tell to user that even if you do not have customization or do not want to customized UI he must enable customization to see just UI in his own locale?
Otherwise, is there any other way to install new locale as a package or set of files to enable new locale without depending on customization service?
May 22, 2008
HarischandraPrasad says:
I have added a new locale(te) and after logging in UI is fine with localized lab...I have added a new locale(te) and after logging in UI is fine with localized labels. But the login page is not showing the localized labels. I have tried by selecting the language in the browser and also verified by giving lang=te in the URL directly like .../iwc_static/layout/login.html?lang=te, but no luck. But if I give the predefined (to Kendo) locale, for ex: "Ko", in the URL it is working fine.
As per my understanding the new locale is part of customization service. So, with out logging into Kendo, how this will be handled or how it will pick up the customized locales? Is there any way to see the login page in customized locales? Do I need to follow any extra steps to achieve this?
May 26, 2008
mangalajlobo says:
The problem here is IWC does not take Browser lang after user login. It falls o...The problem here is IWC does not take Browser lang after user login. It falls on user's preferred lang setting once user is logged in. So even if user selects browser lang to new lang ,it does not help to get UI in that lang. User needs the new lang to be available in the Options->Preferred language list.
now for that - the customization should allow admin to add new lang(customized lang/locale) into preferred lang list.
But how to add new lang to this list ??- the customization guide should include the method or detailed instructions of how this can be added.
[Currently the user has to manually change it in LDAP directly in order to set the preferred lang to a new lang. And then login in order to see UI in the new lang]
May 28, 2008
HarischandraPrasad says:
I have adding the new languages to the list by changing the kernal.js in the dep...I have adding the new languages to the list by changing the kernal.js in the deployed location (.../iwc_static/js/iwc/kernal.js) by adding few more tags like :
\u0c24\u0c46\u0c32\u0c41\u0c17\u0c41
\u0C95\u0CA8\u0CCD\u0CA8\u0CA1
After this the new options are visible to all the users. User able to change his preferred language on his own from the Options->Global ->General page.
But, here as we are modifying the kernal.js(Is this is a supported/accepted way?), which is not in customized folder, what will be the affect if any patch has applied. Will this modified/customized data gets merged with new code or overwrites with new file? I do not have any idea about this.
Aug 25, 2008
Slavek-JES says:
I followed this guide to create the new language (Russian, just for testing purp...I followed this guide to create the new language (Russian, just for testing purposes) and the result is:
Erreur : [Exception... "'Error: Could not load 'c11n.allDomain.js.customize'; last tried '../../../c11n/allDomain/js/customize.js'' when calling method: [nsIDOMEventListener::handleEvent]" nsresult: "0x8057001c (NS_ERROR_XPC_JS_THREW_JS_OBJECT)" location: "<unknown>" data: no]
Aug 25, 2008
Steven_Kahn says:
Slavek-JES: I'm investigating your questions with the Convergence customization ...Slavek-JES:
I'm investigating your questions with the Convergence customization engineering team.
thx,
Steven
Aug 25, 2008
Steven_Kahn says:
Hi Slavek-JES: Got the following response from the experts: "Try clearing the c...Hi Slavek-JES:
Got the following response from the experts: "Try clearing the cache and retrying. Customization at this time does not handle browser caching."
Sep 08, 2008
mangalalobo says:
Here is the observation of trial for Customization-adding new lang support , don...Here is the observation of trial for Customization-adding new lang support , done with latest build.
NOTE:
-currently it worked only for "allDomain" & does not work for any other user specified domains under c11n.
-Please correct the errors in this Document which are mentioned towards end.
-Note also the bugs filed is given at end.
***********
STEPS:
***********
1)Enabled customization parameter using command:
./iwcadmin -u <uid> -W <password file> -p <port number> -o client.enablecustomization -v true
Under Convergence's deployed location i.e <container>/docroot/iwc_static : did the following steps for c11n.
2)Creating "c11n" directory using c11n_sample, under iwc_static: i.e Make a copy of "iwc_static/c11n_sample" & rename it to have "iwc_static/c11n".
3)edited : iwc_static/c11n/config.js : set i18nEnabled flag to true for allDomain in this file.
4)created "ru" as new lang directory : /iwc_static/c11n/allDomain/nls/ru
5)created resources.js file for "ru" : /iwc_static/c11n/allDomain/nls/ru/resources.js
Note: you should have hence the structure as follows:
iwc_static/c11n/allDomain/nls/
iwc_static/c11n/allDomain/nls/resources.js (default one)
iwc_static/c11n/allDomain/nls/ru/
iwc_static/c11n/allDomain/nls/ru/resources.js (this will have localization required for newly added lang "ru")
6)Edited iwc_static/c11n/allDomain/js/customize.js , as follows:
--uncomment the line
dojo.require("c11n.allDomain.js.widget.OptionsViewerGlobalGeneral");
--since i did not need services ,commented the section of helloConvergenceService & also flickrService
--also commented the : dojo.require("c11n.allDomain.js.widget.MailNew");
7)For Adding new lang in Options->General->Prefered lang drop down , did as specified in guide i.e :
Edited :iwc_static/c11n/allDomain/js/widget/OptionsViewerGlobalGeneral.js , & added new : this.language.addChild , as shown in the guide :
with : value: "ru", label: "Russian"
8)For adding label in login page :
edited :iwc_static/layout/login.html
search for div where language references are present & add the line :
<a href="/iwc_static/layout/login.html?lang=ru">Russian </a>
9)Now its done with modifications needed for c11n. So in your Browser clear the Cache. Access the Convergence URL/login page
10)link "Russian" on login page was present & when accessed it changed URL as http://host:port/iwc_static/layout/login.html?lang=ru & showed the login page
11)login as existing english user
12)Go to Options->General->Language . Here in language drop-down , you can see "Russian" . Choose that . Save Preferences & logout
13)Login again as same user . It now picks the localized content that was given in iwc_static/c11n/allDomain/nls/ru/resources.js file.(note:login page strings will not be impacted & there is bug filed as mentioned below)
RESULTS:
So it worked as per above steps.
But following needs to be noted w.r.t one missing info in guide & also the bugs filed below
*********************************
CORRECTION NEEDED IN DOCUMENT
*********************************
Please add this below lines to the above guide(the uncommenting info is missing in guide):
Edit: iwc_static/c11n/allDomain/js/customize.js :
--uncomment the line: dojo.require("c11n.allDomain.js.widget.OptionsViewerGlobalGeneral");
*******
BUGS
*******
1)6745757
2)6745765
3)6745772(BiDi langs specific)
Sep 08, 2008
Steven_Kahn says:
Mangala-- Thanks for your comments. I have updated the page with your correction...Mangala--
Thanks for your comments. I have updated the page with your corrections. Added that you should add resources.js under /allDomain/nls as well as under the particular language directory (Step 5., in "Adding a New Language in Convergence"). Added that you must uncomment ./widget/OptionsViewGlobalGeneral" line in customize.js (new Step 5 in "To Add a Label for the New Language to the Global Options Language Menu.").
Sep 12, 2008
gigibigi says:
I'd put more enphasis on the fact iwc_static/c11n/allDomain/nls/resources.js fil...I'd put more enphasis on the fact iwc_static/c11n/allDomain/nls/resources.js file contains the default localizations.
If you miss that file then only the new language - i.e. Russian - works!
Can such file be empty?
Sep 16, 2008
gigibigi says:
I attempted to localize the Help too but I have not found any instruction. In t...I attempted to localize the Help too but I have not found any instruction.
In the directory iwc_static/layout/help there are the supported languages.
In order to add my language - "it" (italian) - the following routine seems to work.
#cp -Rp en it
#cd it
Translate the content of all the*.html pages (you should have about 160 pages).
I'd appreciate If you write instructions about to add the localized vocabulary for the Compose editor. Thks.
Feb 12, 2009
Saulius23 says:
Have anyone experienced difficulties with Internet Explorer IE7? In our case aft...Have anyone experienced difficulties with Internet Explorer IE7? In our case after adding additional language (lt) it works under Firefox 2, 3 but IE show default en pages.
Feb 13, 2009
joesciallo says:
Saulius23: Looks like known bug. I asked Dev and got this answer: Usually IE d...Saulius23:
Looks like known bug. I asked Dev and got this answer:
Usually IE doesn't like resource.js ending with a comma (,) in the last entry. If this doesn't fix it, do the following:
This should isolate and fix the IE problem.
Joe
Mar 06, 2009
caius1 says:
Hi everyone, i followed customization guide to add Italian to convergence and it...Hi everyone,
i followed customization guide to add Italian to convergence and it works fine with Mozilla Firefox but I obtain an errore when I try to login with IE 7. I'm running Comm Suite 6 u1 on x86 with Patch: 137632-04.
Following the error i have with IE7:
Line: 21
Character: 5357
Codes: 0
Could not load 'c11n.config'; last tried ../../../c11n/config.js
Any Ideas ??
Help appreciate !!!
Mar 09, 2009
nileshp says:
Hi caius1, Good to know that you could solve this problem. NileshHi caius1,
Good to know that you could solve this problem.
Nilesh
Mar 09, 2009
joesciallo says:
Note for Getting Problems Addressed and Resolved In the future, please use the ...Note for Getting Problems Addressed and Resolved
In the future, please use the comments feature on this page to address specific issues with this document. For questions concerning problems with your deployment, please use either the Sun Messaging Server forum (http://forums.sun.com/forum.jspa?forumID=708) or open a support call with Sun.
Thanks,
Joe