DITA CHM for Chinese and Japanese

[leo71]

Hi there,

Is there anybody who succesfully compiled CHMs from XMetal DITA?
I have tested this on Windows 7 64bits with the out of the box XMetal 6 SP1 Version#: 6.0.2.070 with all default settings, just DITA 1.1, and no additional ANT params and so on.
HTML Help Workshop: 4.74.8702.0

The language is set on all topics and the ditamap to xml:lang=”zh-CN”

* Topics are compiled and show up fine.
* TOC, Index show up with Chinese characters (not squares)
* BUT in between the Chinese characters and sometimes at the end are additional characters. My Chinese understanding is bad 🙂  but it is easy to compare the TOC label with the target title.

When I open the HHC and HHK file, these look good, but they are in UTF-8.
In other XML (non DITA) projects I could get this thing working fine, but I had to use:
– GB2312 for Chinese
– Shift-JIS for Japanese
for HHK, HHC, and maybe the HHP. The topics can stay UTF-8.
I am not sure if you have to use the binary compile for Index/Contents.

So, I am wondering if this could ever work 100% in this configuration.

Reply

[Derek Read]

Yes, you can get this working.

Basically, the issue is that because HTML Help Workshop is not a Unicode-aware application (and never will be because Microsoft is no updating it) you either need to run it on a Windows machine configured for your target encoding/language (ie: Chinese / Japanese), or you need to use a tool called AppLocale (from Microsoft) to tell Windows to run the application as it if were running on such a machine.

I thought we had documented this somewhere officially but perhaps not. A full answer will be fairly long, so please give me a while to write something up.

Reply

[leo71]

As far as I know the AppLocale utility is in use by the DITA OT.

Reply

[Derek Read]

AppLocale does not come with nor is it used by the DITA OT (at least the version we bundle which is 1.4.2.1). It is a separate download provided by Microsoft for switching the locale when running old software. It is not included with Windows either so you must install it separately. I will provide a complete set of instructions as soon as I can.

Reply

[Derek Read]

OK, I've found an old document I wrote and provided to a few larger clients years ago when this feature was considered experimental. We get the occasional request through our official support channel and send instructions out individually so we never put it into our official documentation. I've cleaned it up a little and attached an HTML version.

It does not contain specific information for Chinese and Japanese, and it mentions that it was tested for XMetaL Author Enterprise 5.1 but these instructions should be usable without modification for the 6.0 and 6.0 SP1 releases because this functionality has not changed (at least in any way that I can think of that would affect this). These instructions have been tested by three of our larger clients (as well as others) that need to produce CHM in multiple languages so hopefully you can use them to get your system configured as well.

One of these clients is producing CHM output in upwards of 30 languages for their products. Unfortunately, I do not have the complete listing of the settings they required for all languages. However, the settings for the languages I list in this document under “Sample Parameter Value Sets” were tested by me so I know they work. You will need to find the settings for any languages not listed (I describe how to do that as well). If you test additional settings that work for specific languages and you wish to share them please do so and I can then improve the list.

Reply

[Derek Read]

Just found another (pretty much identical) copy of those instructions from 2008 in case you prefer them as PDF:
http://forums.xmetal.com/index.php/topic,98.msg262.html#msg262

Reply

[leo71]

It is a pity that the document is slightly outdated in our situation:
– Windows 7 and/or Windows 2008 R2 Server
  Language packs are installed in a different way
– It is different to install the applocale utility and officially it looks like it is not supported under Win7

Sorry to be stubborn, but I have a batch running on Windows 2008 R2 Server (which also works fine under Win7).
1. I convert all proprietary XML topics to UTF-8
2. Next the HHP, HHK, and HHC are converted to the GB2312 (or Shift_JIS for Japanese).
And all functionality works fine.

Now back to DITA XML.
If I postprocess the the DITA OT generated files and get the HHP, HHK, and HHC everything also works fine. Except the full text search. I can enter English words fine, but Chinese/Japanese words are not found. (But I should ask our Japanes/Chin. translators to test this)

Just for your info.

Reply

[Derek Read]

Running the software on Windows 2008 is not something we test or support so I can't help there much.

Ultimately, the issue here is HTML Help Workshop. Microsoft does not provide a Unicode-aware version of that software and from what I have read they do not plan to (last release was 2003). Running that software on a machine with the right Windows locale should allow it to produce output for that locale. Using applocale merely lets you run an application using a different Windows locale from your system's locale.

Perhaps you could set up a second (and possibly 3rd) machine just for this purpose running the proper locale (Japanese / Chinese)? It would not need anything but HTML Help Workshop installed in order to complete the last stage in the output generation process (generating the CHM file from the HHP, HHC, HHK inputs).

Another option would be to install everything to “XP Mode” on your Windows 7 box: http://www.microsoft.com/windows/virtual-pc/download.aspx

You might also look into the Japanese version of HTML Help Workshop, though I don't know that it will help (and there is no Chinese-specific version): http://www.microsoft.com/download/en/details.aspx?id=21138

Reply

[mmoulder]

We created a separate delivery for each language for chm. Here is what we used for the deliver in the advance tab under the other output parameters:
Japanese”
RX_CUSTOM_DIR  =  %DITA_OT_DIR%demoxmfoCustomization.decho
ANT_PARAM_args.dita.locale  =  ja-JP
ANT_PARAM_args.htmlhelp.charset  =  Shift-JIS
ANT_PARAM_args.htmlhelp.language  =  0x411 Japanese
ANT_PARAM_args.htmlhelp.runapplocale.param  =  /L0411
ANT_PARAM_args.htmlhelp.runapplocale  =  C:WINDOWSAppPatchAppLoc.exe
ANT_PARAM_args.htmlhelp.skipCompilation  =  yes
ANT_PARAM_args.css  =  %DITA_OT_DIR%chm_customcustom.css
ANT_PARAM_args.copycss  =  yes

Chinese Simplified:
RX_CUSTOM_DIR  =  %DITA_OT_DIR%demoxmfoCustomization.decho
ANT_PARAM_args.dita.locale  =  zh-CN
ANT_PARAM_args.htmlhelp.charset  =  gb2312
ANT_PARAM_args.htmlhelp.language  =  0x804 Chinese_PRC
ANT_PARAM_args.htmlhelp.runapplocale.param  =  /L0804
ANT_PARAM_args.htmlhelp.runapplocale  =  C:WINDOWSAppPatchAppLoc.exe
ANT_PARAM_args.htmlhelp.skipCompilation  =  yes
ANT_PARAM_args.css  =  %DITA_OT_DIR%chm_customcustom.css
ANT_PARAM_args.copycss  =  yes

Reply

[Derek Read]

I've updated these instructions to include mmoulder's settings for Chinese and Japanese (those settings that are specific to configuring XMetaL to use  AppLocale). See attached zip.

If anyone else has settings they have tested please let me know and I will bundle them into an updated version for others that might find this useful.

Reply

[Author]

Posts