• DavidShaked
• LocalizingWWePProjects

Generating Localized Help in WebWorks ePublisher

David Shaked (Wernick), AlmondWeb Ltd., http://www.almondweb.com

One of the greatest strengths of WebWorks ePublisher (WWeP) is its language support. I have successfully used WWeP to generate help output in languages such as English, French, German, Japanese, Chinese, Russian, Greek, and Hebrew. I have processed all these languages on an English Windows computer. In most cases, I have used the identical WWeP stationery as for English, with at most a few simple localization steps. I happen to know French and Hebrew, but I do not know the other languages. Translators of those languages reviewed the help output and assured me that the output is correct.

In this article, I have tried to distill my experience and provide instructions for localizing a WWeP project. The article assumes a scenario where you have written the source documents in English and you have processed the documents in WWeP. You are now sending the documents to a localization vendor who uses WWeP Express. The article explains what you must send to the vendor and what the vendor must do to create the localized help output.

In an alternative scenario, you can ask the vendor to send the localized source documents back to you. You can process them in WWeP Express yourself. If you choose that approach, modify the following procedures by performing the "vendor" instructions yourself.

System Requirements

These instructions have been tested in WWeP 2011.4 running on Microsoft Windows 7. With minor variations, the same instructions apply to all WWeP and Windows versions.

The localization vendor needs a WWeP Express version that is the same or later than the version that you used to create the WWeP stationery. If the vendor has an earlier WWeP Express version than you, it might fail to process the stationery.

You and the vendor can install WWeP on an English Windows version. There is no need to use a localized Windows version. However, the vendor might need to add fonts or edit locale settings for the target language, as explained below.

In the WWeP Express setup, select the option to allow the user to view the target settings, cross-reference settings, conditions, and variables. This option is critical for localization projects.

What You Must Send to the Localization Vendor

You must send the following files to the localization vendor:

• Word, FM, or DITA source documents
• The WWeP stationery

In most cases, it is sufficient to send the same stationery that you use for English help projects. There might be an exception to this rule if you need to localize any stationery features that you have defined in the Style Designer or in project overrides. For example, you might need to localize the following stationery features:

• Bullet text that you have hard-coded in the Style Designer
• For Asian languages, font settings that are defined in the Style Designer
• Text that you hard-coded in a Page.asp override

In some languages such as Japanese, it is not customary to use italic fonts. If the English help uses italic formatting, and the italics are defined in the Style Designer as opposed to the source document, consider changing the Style Designer setting to bold.

In the Target Settings, examine the Locale drop-down list, and confirm that the target locale is supported. If not, you must provide a custom locale setting. For instructions, see Adding a Locale to WebWorks below.

For right-to-left (RTL) languages such as Hebrew and Arabic, there are some additional steps to prepare the stationery. For RTL instructions, please contact AlmondWeb.

What the Localization Vendor Must Do

1. Translate the source documents, preserving the original formatting.

2. On the WWeP Express computer, edit Control Panel > Regional and Language Options. Add support for the target language. For example, install Asian fonts or any other options that are required to view the language.

3. Depending on the language and the output format, you might need to set the Windows system locale before you generate the help. Otherwise, the full-text search might not work or the index might be displayed incorrectly.

   The system locale setting is required, for example, if you generate CHM output in a non-Western European language. After you generate the help, you can change the system locale back to English (but see Viewing the Localized Output below).

   • On Windows XP, the system locale setting is located at Control Panel > Regional and Language Options > Advanced > Language for Non-Unicode Programs.

   • On Windows 7, the system locale setting is located at Control Panel > Clock, Language, and Region > Region and Language > Administrative > Change System Locale.

4. Create a WWeP Express project based on the existing WWeP stationery, and add the localized source documents.

5. In the Target > Target Settings window, set the required encoding and locale.

6. If required, edit additional settings, for example:

   • In Target > Target Settings, localize the company information.

   • In Target > Cross Reference Rules, localize any hard-coded text.

   • In Target > Merge Settings, localize the merge title and the TOC titles.

   • In Target > Variables, localize the variable values.

1. Generate the project.

Viewing the Localized Output

You can view and test the WWeP output in exactly the same way as English output.

If you view the output on an English computer, there might be some display limitations. For example, the "Contents", "Index", and "Search" navigation labels might remain in English.

To view the fully localized output, you might need to set some locale options in your computer or in the viewing software. The following paragraphs provide instructions for viewing specific output formats. For other output formats, you might need to experiment to find the required settings. Alternatively, ask a translator who has a fully localized computer to view and test the output.

Viewing Fully Localized WebWorks Help Output

To view WebWorks Help with a fully localized interface, you must set the locale of the web browser.

To set the locale of Microsoft Internet Explorer, set the Windows user locale.

• In Windows XP, the setting is located at Control Panel > Regional and Language Options > Regional Options > Standards and Formats.

• In Windows Vista, the setting is located at Control Panel > Clock, Language, and Region > Change the Date, Time, or Number Format > Formats > Current Format.

• In Windows 7, the setting is located at Control Panel > Clock, Language, and Region > Region and Language > Formats.

To set the locale of Mozilla Firefox:

1. Open Firefox.

2. On the menu, click Tool > Options.

3. Display the Content tab.
4. In the Languages section, click the Choose button.
5. Add the target language, and make it the first choice in the preference list.

6. If the WebWorks Help output is already displayed, reload it.

To set the locale of Google Chrome:

1. Open Chrome.
2. At the right end of the toolbar, click the button to Customize and Control Google Chrome.
3. In the drop-down menu, click Options.
4. In the left pane, select Under the Hood.
5. In the right pane, find the Web Content section and click Languages and Spell-Checker Settings.
6. Add the target language to the language list.
7. Click the button to Display Google Chrome in this Language.
8. Close and re-open Chrome.

Viewing Fully Localized CHM Output

To view a CHM with a fully localized display, set the Windows system locale to the target language. For instructions, see What the Localization Vendor Must Do above.

With certain languages on Microsoft Windows 7, you must install a Windows language pack and switch the Windows user interface to the target language:

1. From Windows Update, download and install a Hebrew language pack for Windows.

2. In the Windows Control Panel, open Clock, Language, and Region > Region and Language.

3. Display the Keyboards and Languages tab.
4. In the Choose a Display Language option, select the language. You are prompted to log off and log back on.
5. After you view the help, change the user-interface language back to English.

Adding a Locale to WebWorks

WWeP is supplied with out-of-the-box locale settings for many languages. Each locale setting includes localized user-interface display strings and other language-specific information. You can add settings for other locales and languages.

To view the list of locale settings provided with WWeP:

1. Open any project in WWeP Pro or Express.

2. On the menu, click Target > Target Settings.

3. Find the Locale option, and open the drop-down list of locales.

To add a locale setting:

1. Create overrides for the following files:
   • Formats\Shared\common\locale\locale.fti
   • Formats\Shared\common\locale\locales.xml
   Store the overrides in one of the following subdirectories of the WWeP project directory:
   • [Project Directory]\Formats\[Format Name]\Shared\common\locale\
   • [Project Directory]\Targets\[Target Name]\Shared\common\locale\
2. In the locale.fti override, find the list of Common elements, and add the following line:

   • <Common value="LanguageCode" />

   The LanguageCode is an identifier for the target language, such as "en" for English or "fr" for French.

3. In the locales.xml override, copy the English locale, and localize the copy to the target language.

   For detailed instructions, see locales.xml. For a list of the LCID locale identifiers, see http://msdn.microsoft.com/en-us/goglobal/bb964664.

4. If you are generating WebWorks Help, you must also create an override for the following file:

   • Formats\WebWorks Help 5.0\Files\wwhelp\messages.xml

   Store the override in one of the following subdirectories of the WWeP project directory:

   • [Project Directory]\Formats\WebWorks Help 5.0\Files\wwhelp\

   • [Project Directory]\Targets\[Target Name]\Files\wwhelp\

   Copy the English locale, change "en" to the target LanguageCode, and localize the nested display strings.