|
HTML Help Localization and Internationalization |
HTML Help (Wikipedia) is Microsoft's help system 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. After reading this document, we recommend reading a tutorial about how to use Soluling.
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 structures, 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 website. 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.
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 Windows code pages or UTF-8. Later 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 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. Suppose 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.
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.
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 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, 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 | 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 is 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 contains following HTML Help samples:
| Directory | Description |
|---|---|
| SortAlpha | A sample that shows alphabetical 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. |
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, Word, PowerPoint, Markdown, RTF, and PDF files.
Copyright © 2010-2024 Soluling