Note that this is a developer’s tool. It is not a general purpose tool. The application will not run as is - it must be first configured for your project. Please read these instructions for details on using this tool, and see my blog here and here for details on how this tool works and other uses of the tool.



Give the appearance of a single document, written in the language of the user


Universal Document is a simple tool that allows a developer to create an application that appears as a localised document to the end-user. This “document” will have a name in the native language of the user, and will display documentation in that language when opened.


As an example, take Apple’s Mac OS X. A typical OS X install DVD looks something like the following:



An example of multiple localised documentation without Universal Document


As can be seen in the example above, the documentation shown to the user is actually in English. If the user does not understand English, they may wonder what to do. However, there are folders for other languages, so the user is expected to click there first, read the documents inside, then go back to install.


Universal Document can replace multiple files and directories with a single “document” - an application that will open the correct document for the user’s locale.  Converting the above example in to a Universal Document, results in the following for someone with English localisation:




Someone using German localisation would see:




And a Japanese user would see:




There is no need for the user to open folders to get to the documentation - they see their documentation straight away on open of the folder, disc or volume where the Universal Document resides.


How do I use this?

The tool is non-trivial to use.  You must follow these instructions carefully:


  1. 1. Download Universal Document.  Make a copy of the Universal Document application in a folder of your choice.


  1. 2. Select the copy of Universal Document in the finder. Bring up the Info pane (right click and choose “Get Info”, or hit CMD-I).


  1. 3. In the Info pane, change the Name & Extenstion to “NameOfYourApp Documentation.app” (or something similarly unique).


  1. 4. Right click on your Universal Document and select “Show Package Contents”. Navigate through “Contents”.


  1. Edit the Info.plist file.  Change the entry that reads:


  2. <key>CFBundleDisplayName</key>

  3. <string>Universal Document</string>


  4. to


  5. <key>CFBundleDisplayName</key>

  6. <string>NameOfYourApp Documentation</string>


  7. and save your changes.


  1. 6. Now navigate to the “Resources” folder.


  1. In Resources you will find an example “English.lproj”.  Make copies of this folder and rename for each language you want to support.  For example, “German.lproj”, “Japanese.lproj”.  You can also use Language and Regional Designations - for example “en_AU.lproj” for Australian English etc.  See Apple’s Developer Documentation and the following list of codes for more information.


  1. 7. In each “lproj” folder, edit the “InfoPlist.strings” file.  By default it will look like:


  2.     CFBundleDisplayName = "Universal Document";

  3.     OpenName = "Insert Document Name.extension";


  4. Change CFBundleDisplayName to the text the user should see as the label on the document, and OpenName to the name of the file to open.


  5. Copy the file you mentioned in OpenName to this folder.


  6. You can also use a URL and have the Universal Document go to that web page when launched. In this case, there is no need to add a file to the folder, only to edit the file to include the URL.


  7. If you do not want the document to open any files or URLs, delete the OpenName line in the file.


  1. 8. Once you have changed each locale’s details, make a copy of your new app to another folder. You need to do this for the Finder to realise things have changed.


You now have a Universal Document for your application. You can test it by changing Language in your System Preferences International settings, and relaunching the Finder (Go to Apple menu, Force Quit, and select the Finder).


What documents can I use?

You can basically open any document - txt, rtf, pdf, etc. You can also open a subfolder if you like (the example below, for Japanese users, opens a folder with two documents in it, rather than just a single document).


You can also use a URL - for example http://example.com/order.html.


If you don’t want anything to open at all, delete the OpenName line in the file.


Do you have an example?

Yes. Download the example below - it is taken from the Mac OS X 10.2 Installation instructions (first DVD I picked up when putting examples together).


Isn’t this dangerous? Couldn’t someone hide a Trojan as a document?


Well, it is no more dangerous than someone hiding any Trojan in an application. You shouldn’t open any files (documents or applications) unless you trust the source.


How much does Universal Document cost?

Universal Document is free.  Developers are welcome to use it for their own projects (free or commercial), and I expect nothing in return. Though an e-mail saying you are using it is always nice.  And if you want to make a donation, that always helps. :-)



 

Requirements

+ PowerPC or Intel Macintosh


Icon

The icon used by Universal Document was provided by Adam 'Elroy' Mazzitelli (http://www.elroyonline.com)


Disclaimer

No warranty is made to Universal Document’s usefulness, and no responsibility will be taken for loss incurred through its use or misuse.





Universal Document 1.1    NEW!

An Example Universal Document

Source Code (for those who want it)






Universal Document is Copyright © 2005-2010 Jamie Curmi (curmi.com), All rights reserved.