Creating a localised mac help book file (.help)

Question

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?

Richard Garside · Accepted Answer · 2018-11-21T10:40:57.330

4

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.

edited Nov 21 '18 at 10:40

answered Jul 02 '12 at 15:30

Richard Garside

87,839
11
80
93

Hmm - the localized structure works just fine for me. I wonder what I've done differently as it looks like in your Ascii-Art folder structure for me as well. Just two locales, but working fine. – Jay Dec 02 '15 at 17:26
The site you preferred is not in English. Any chance, you put together a simple steps how to create a simple help folder. Apple's doc on this is terrible. – user523234 Feb 12 '16 at 13:21
@user523234 The page can be translated by clicking the flags at the top of the page. I've updated the link so it goes straight to the English version. – Richard Garside Feb 16 '16 at 22:28
1

@RichardGarside The linked article is missing. Also I'm encountering the same problem. – adib Nov 19 '18 at 23:32
1

@adib fixed to use Internet archive version of the page – Richard Garside Nov 21 '18 at 10:41

score 1 · Answer 2 · answered Nov 25 '15 at 23:32

1

You should localize some of your Info.plist keys after you localized the help book resources.

The keys CFBundleName and HPDBookTitle should be localized using InfoPlist.strings files.

answered Nov 25 '15 at 23:32

Vladimir Afinello

1,211
14
16

Creating a localised mac help book file (.help)

2 Answers2