Search code examples
macosapple-help

Creating a localised mac help book file (.help)

I had created the help for my app in just one language in a folder and it worked. I've tried and failed to localise this content and add a Spanish translation.

My understanding of Apples Guide to creating a help book is that I need to create a .help package for localisation to work. I've done that, but I get an error saying "The selected topic is currently unavailable.". There have been a few times when I thought it was working, but it was just showing the pre localised content I had. Emptying the help viewer cache seems to stop that, but then I go back to getting the unavailable content error message.

In my app's AppName-Info.plist file I have the following help related entries:

<key>CFBundleHelpBookFolder</key>
<string>AppName.help</string>
<key>CFBundleHelpBookName</key>
<string>garsonix.appname.help</string>

My AppName.help file has the following structure:

AppName.help
    Contents
        Info.plist
        Resources
            English.lproj
                index.html
                search.helpindex
            Spanish.lproj
                index.html
                search.helpindex
            shrd
                logo.png

The Info.plist file inside AppName.help has the following keys:

<key>CFBundleDevelopmentRegion</key>
<string>en_GB</string>
<key>CFBundleIdentifier</key>
<string>garsonix.appname.help</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundleName</key>
<string>AppName</string>
<key>CFBundlePackageType</key>
<string>BNDL</string>
<key>CFBundleShortVersionString</key>
<string>1.13</string>
<key>CFBundleSignature</key>
<string>hbwr</string>
<key>CFBundleVersion</key>
<string>1.13</string>
<key>HPDBookAccessPath</key>
<string>index.html</string>
<key>HPDBookIconPath</key>
<string>shrd/logo.png</string>
<key>HPDBookKBProduct</key>
<string>GAppName</string>
<key>HPDBookKBURL</key>
<string>http://www.garsonix.co.uk/</string>
<key>HPDBookRemoteURL</key>
<string>http://www.garsonix.co.uk/</string>
<key>HPDBookTitle</key>
<string>AppName Help</string>
<key>HPDBookType</key>
<string>3</string>
<key>HPDBookIndexPath</key>
<string>search.helpindex</string>

Does anyone know what I'm doing wrong, or know of a good tutorial on making .help files?

Solution

  • I finally got this working, but I had to abandon the .help file format.

    I instead kept my old simple help folder, which I duplicated for each language. Each of the help folders was then put in the existing localised folders of the main app package along with the localised nib files.

    I found the instructions in this article very helpful: https://web.archive.org/web/20150421040211/https://www.icalamus.net/ioda/howto_applehelpbook.php?lan=en

    I'd still like to know how to get the .help format working, but this has solved my problem and seems much simpler. The only slight disadvantage is there is no way of sharing resources like images that do not need localising.