Document home

HTML Help

HTML Help Localization and Internationalization

HTML Help (Wikipedia) is Microsoft's help system that is used to provide online help for Windows applications. HTML Help file is a one CHM file that is a compressed file containing HTML, image, and navigation files. Soluling localization tool and service support HTML Help.

The end of the document contains links to get the full source code of the samples.

Process

Soluling reads the original HTML Help file (.chm) to extracts pages and other items. Finally, when building, Soluling creates localized HTML Help files. There is one output file (.chm) for each language. You don't need to have HTML Help source files. The only file you need is the original HTML Help file.

Create a new project for your HTML Help file (.chm). The Project Wizard appears, showing the options sheet that lets you set the localization options. Once the project is created, you can start translating it. The final step is to create localized HTML Help files. Soluling creates localized HTML Help files in language-specific directories. For example, if your original file is C:\Files\Sample.chm and you added German and French in the project, Soluling creates C:\Files\de\Sample.chm and C:\Files\fr\Sample.chm. All three HTML Help files have identical structure, but the data such as text, navigation data, and optionally images, have been translated.

To build localized HTML Help files, you need to install the Microsoft HTML Help Workshop that is freely downloadable from Microsoft's web site. When creating localized files, Soluling automatically uses the HTML Help Workshop to compile localized files.

If you check Do not compile localized CHM file but create only the source files checkbox in Options sheet Soluling does not create localized CHM file, but it creates localized HTML Help project files including all source files. Then it is up to you to compile .hhp file into .chm file using the help compiler.

Some issues

HTML Help is an old product (the last update is from 2003). It is not fully Unicode enabled. This brings some limitations that you should know when writing HTML Help files. The most important issue is that you should use only ASCII characters as HTML Help file names. This includes all files such as HTML, image, project, and navigation files. Your HTML files can either use either Windows code pages or UTF-8. Later is recommended.

Why does my localized CHM window show the title "HTML Help" instead of my title?

This is a feature of HTML Help viewer. It shows the title correctly only if the language id of the CHM file matches exactly the current language of your computer. You have to go to Control Panel and change the system locale to match the language of your CHM file to show the title correctly. However, the end-user of the localized CHM file has most likely the language id compatible to the language id if the CHM file and he or she will see the title text correctly. Soluling has an option for this issue. If you check Use compatible language id whenever possible checkbox in Options sheet Soluling will set the language id of the localized CHM file to English (United States) if the target language is not English and it uses Western code page 1252. This makes the title of CHM rendering correctly.

Help authoring tools

Some help authoring tools (HAT) have added their modifications to HTML Help. For example, HTML Help files created by RoboHelp (Wikipedia) may contain browse sequences, glossary, and language files. Soluling also localizes these RoboHelp specific additions.

Items

An HTML Help file contains several different items or sub-files embedded into a single HTML Help file (.chm). Soluling localizes these items. The best way to go through items is by an example. The following table contains the project tree of a Soluling project that has one HTML Help file, Sport.chm. The tree shows all the items the file contains.

  Icon Item Description
Project tree HTML HTML files HTML files are the main building blocks of an HTML Help file. Each HTML file in the HTML Help file represents a single page.
Basketball.htm is one HTML file in our sample. The sample contains several other HTML files.
Image Image files Most HTML files contain images. HTML Help contains all the images used by the HTML files.
Basketball_Ball.png is one image file in our sample. The sample contains several other image files.
Folder Folders Most HTML Help files contain so many pages and images that it would be impractical to have everything in a flat directory. This is why HTML Help can contain any number of subfolders that store other files and folders.
Large is the only folder in our sample. The folder contains large sports images.
Script Script files Like other HTML pages also pages in HTML Help can use scripts. Learn more about script localization.
ehlpdhtm.js is one script file in our sample.
Note! By default, Soluling does not scan script files.
Navigation Navigation HTML Help files contain several navigation items. To make it easier to find and edit them, Soluling groups all navigation elements inside a navigation node. The project tree contains one Navigation node for each HTML Help file that has been added into the project.
Navigation is the navigation node is our sample.
Window Viewer HTML Help contains some strings that are used by the HTML Help Viewer application. The viewer node contains such strings.
Contents Contents Most HTML Help files contain a table of contents (TOC). If present, the Navigation node contains the Contens node, that contains all the possible sub-nodes.
Contents node is the root TOC item, and Sports is a sub-item in our sample.
Index Index Most HTML Help files contain index data. If present, the Navigation node contains an Index node that contains all strings used in index data.
Index node is the index item in our sample.
Sequence Sequence Some HTML Help files contain browse sequence data. If present, the Navigation node contains a Sequence node that contains all the sequences.
This is a RoboHelp specific item. Only HTML Help files created by RoboHelp may contain this item.
Glossary Glossary Some HTML Help files contain glossary data. If present, the Navigation node contains a Glossary node that contains all the glossary items.
This is a RoboHelp specific item. Only HTML Help files created by RoboHelp may contain this item.
Language Language Some HTML Help files contain language string data. If present, the Navigation node contains a Language node that contains all the language string groups. Each group contains one or more strings.
This is a RoboHelp specific item. Only HTML Help files created by RoboHelp may contain this item.

About scripts and images

By default, Soluling scans all items from HTML Help files except script files. If you have hardcoded strings in your script files and you want to localize them, you have to enable script scanning. Check Scan script files checkbox in Options sheet to enable script localization. If you want to disable the image scanning, uncheck the Scan images checkbox in the HTML options sheet. If you want to disable the scanning of an individual item, select the item in the project tree, right-click, and check the Excluded menu item.

Errors and Warnings

The following table contains errors and warnings that might appear during scanning or building an HTML Help file.

Name Type
No HTML Help Workshop Error
Could not extract files Error
No East Asian language files Warning
Invalid file name Warning

Samples

GitHub and <data-dir>\Samples\HtmlHelp contains following HTML Help samples:

Directory Description
SortAlpha A sample that shows alphapetical contents sorting feature.
SortStandard A sample that shows contents sorting feature.
Sport A simple HTML Help sample.
SortRoboHelp As above but enhanced with RoboHelp items such as browse sequences and glossary.

Configuring HTML Help Localization

You can configure how to localize your HTML Help file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

Read more about other document files such as DITA, HTML, HTML Help, Word, PowerPoint, Markdown and PDF files.