|
HTML Help Localization and Internationalization |
HTML Help (Wikipedia) is Microsoft's help system used to provide online help for Windows applications. An HTML Help file is a single CHM file that is a compressed file containing HTML, image, and navigation files. Soluling supports HTML Help.
The end of the document contains links to get the full source code of the samples. After reading this document, we recommend reading a tutorial about how to use Soluling.
Soluling reads the original HTML Help file (.chm) and extracts the pages and other items. When building, Soluling creates localized HTML Help files. There is one output file (.chm) for each language. You don't need to have the 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 the localized HTML Help files: choose Home | Build All. Soluling creates the 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 to the project, Soluling creates C:\Files\de\Sample.chm and C:\Files\fr\Sample.chm. All three HTML Help files have identical structures, but the data, such as text, navigation data, and optionally images, have been translated.
To build localized HTML Help files, you need to have Microsoft HTML Help Workshop installed. When creating localized files, Soluling automatically uses HTML Help Workshop to compile the localized files. Note! Microsoft no longer offers HTML Help Workshop for download on its website. If you do not already have it, install it from an existing installation package or a trusted archive copy.
If you check the Do not compile localized CHM file but create only the source files checkbox on the Options sheet, Soluling does not create a localized CHM file, but it creates localized HTML Help project files, including all source files. Then it is up to you to compile the .hhp file into a .chm file using a help compiler.
Cloud processWith Soluling Cloud, you and your translators can translate the help file in a browser using Translate. Because the localized CHM files are compiled with HTML Help Workshop, create the project in Soluling Desktop, upload it to Soluling Cloud, and build the localized files in Soluling Desktop. You need a Soluling account. See the available Cloud plans.
.ntp).When the original help file changes, choose Home | Scan in Soluling Desktop, click Upload to Cloud, translate the new and changed items, and import and build again. See the Cloud tutorial.
HTML Help is a very 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 in HTML Help file names. This includes all files, such as HTML, image, project, and navigation files. Your HTML files can use either Windows code pages or UTF-8. The latter is recommended.
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 most likely has a language ID that is compatible with the language ID of the CHM file, and they will see the title text correctly. Soluling has an option for this issue. If you check the Use compatible language ID whenever possible checkbox on the Options sheet, Soluling sets the language ID of the localized CHM file to English (United States) if the target language is not English and it uses the Western code page 1252. This makes the title of the CHM file render correctly.
Some help authoring tools (HAT) have added their own 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.
If you use Help+Manual, do not localize the CHM files it produces but localize the Help+Manual project.
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 the items is by 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 | |
|---|---|---|---|
 |
 |
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 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. |
|
 |
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 files | Like other HTML pages, pages in HTML Help can also 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 | 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 to the project. Navigation is the navigation node in our sample. |
|
 |
Viewer | HTML Help contains some strings that are used by the HTML Help Viewer application. The viewer node contains such strings. | |
 |
Contents | Most HTML Help files contain a table of contents (TOC). If present, the Navigation node contains the Contents node that contains all the possible sub-nodes. The Contents node is the root TOC item, and Sports is a sub-item in our sample. |
|
 |
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. The Index node is the index item in our sample. |
|
 |
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 | 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 | 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. |
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.
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 filename | Warning |
GitHub and <data-dir>\Samples\HtmlHelp contain the following HTML Help samples:
| Directory | Description |
|---|---|
| Sport | A simple HTML Help file that contains pages, images, a folder, a table of contents, and an index. This is the sample that the Items chapter uses. Study this first. |
| SportRoboHelp | As above, but enhanced with RoboHelp items: a browse sequence (Sport.brs), a glossary (Sport.glo), and a language file (RoboHHRE.lng). |
| Sort | A sample that shows the Contents sorting option of the Options sheet. The table of contents contains vehicles whose order changes when the names are translated. The localized file is in the fi subdirectory. |
Each directory contains the original .chm file, its HTML Help project (.hhp) and source files, and the Soluling project.
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, Help+Manual, HTML, HTML Help, LaTeX, Word, PowerPoint, Markdown, RTF, and PDF files.
Copyright © 2016-2026 Soluling Oy