Create Custom Dictionaries For Mac OSX

Over the last couple of months I’ve been chipping away at creating an add-on dictionary for the Dictionary application on Mac. I wanted to create a dictionary for CFWheels.

Information on how to create such dictionaries was not all that easy to find. So I thought I’d share what I found in case it helps some else.

Apple’s Dictionary Services Programming Tutorial

First up, have a look at this tutorial on Dictionary Services Programming over at developer.apple.com. It provides all the information one needs to get started. You can also download a PDF of this tutorial.

Template Files for Dictionary

One thing that the tutorial assumes is that you have the template files for dictionary development are. First challenge was to figure out where they were. I found that they are installed with XCode at: /Developer/Examples/Dictionary Development Kit. If you don’t have XCode installed, then you can download the this zip file that contains the Dictionary Development Kit.

The Make Command

Before you customize anything in these files, simply run ‘make’ command in directory where you unzip these files. It should create a dictionary called “My Dictionary”. If you move this dictionary to /Library/Dictionaries or ~/Library/Dictionaries, it will start showing up i the Dictionary app.

There are a couple of other things that the make command can do:

• make clean : cleans older builds
• make install : installs the created dictionary to ~/Library/Dictionaries folder
• make : creates the dictionary

Change the XML and Info.plist

Now add the stuff you want in the XML that will be used to create the dictionary. You will have to generate the XML with the appropriate structure and content. Also modify the plist file as required. Run “make” to create your dictionary.

A Big Gotcha – Cached Dictionaries

On thing that really had me flummoxed was that despite making a new dictionary, the Dictionary app was not reliably showing all the changes I expected.

This took a while to figure. There is a bunch of caching that comes into play if you are creating new builds of the dictionary. Cached versions show up and throw you off the track.

So I had to write this shell script to clean Dictionary app cache. Make sure that you

• make the script executable before running it, and
• quit the Dictionary app before you run

I found that I had run this each time I made a change to the XML file.

A downside to doing this is that it resets all Dictionary preferences. So when you start the Dictionary app after running this script, you have go to Preferences and turn on the dictionary you are working on. A bit painful, but not such a biggie.

My Development Workflow

So as I was making changes to the XML file with data, I was running the following commands:

• ./clean.sh (cleans out all dictionary caches)
• make clean (cleans out older builds of the dictionary)
• make (makes the dictionary)
• make install (installs the dictionary)

Example Dictionary: CFWheels

If you want to see an example of the dictionary that I created, check out: https://github.com/indynagpal/CFWheels-Mac-Dictionary

Look at the XML and Info.plist files.

That’s it… go and have fun creating dictionaries now!