LargoRecipes in Your Language

I've received several requests for internationalisation of LargoRecipes - that is, translating every feature of the program into a target language, so speakers of that language can easily use it. The good news is that LargoRecipes version 0.9.1 is fully internationalised, so that translators can use a fairly simple process to convert prompts, error messages, help screens, and reference data into a new language. This page tells you how to get LargoRecipes running in your favourite language!

Some translations may already be available - so your first stop should be the download page to see if yours is already available. If a full translation isn't available, maybe a partial one is - again, look on the download page for instructions.

If the translation you want isn't there, you'll need to do the translation yourself. This may seem like a big task, but realise that you don't have to do it all at once - you can do some now and some later, or work with partners to finish different parts of the task. See the LargoRecipes user forums to find partners interested in helping you do translations.

Below, you'll find very detailed instructions for translation. Don't be put off by the detail, because it's not that hard: you download and uncompress some files, find the right parts of each file to translate, do the translation, and recompress. (I'd like to make this process easier eventually by providing a wizard-like graphical walkthrough right inside LargoRecipes, but it's not too hard to do even without hand-holding.)

Note to Chinese, Japanese, and Korean speakers: Java can't display these languages without some tweaking. Details are at the bottom of this page.

Getting the right tools

First, make sure you have the latest version of LargoRecipes - see the download page for instructions.

Next, make sure you have access to a zip utility. Linux users should have one as part of the operating system - type zip -h at a command line to check. Windows users may want to download programs like 7-Zip or WinZip. Macintosh users - sorry, but I don't know any zip programs for you (I'm sure there are some though).

Make sure you have a text editor that can save text files in the UTF-8 encoding correctly. An encoding is a way of translating characters into numbers, and UTF-8 is the encoding LargoRecipes uses. UTF-8 is a common standard that lets you represent nearly any character from nearly any alphabet in the world, including Asian pictograms (Chinese, Japanese, etc.), Arabic, Russian, and many others.

The text editor I use is jEdit, but I'm sure there are many others equally good. Whichever you choose, use it to edit all the files mentioned below, and always make sure to save with the UTF-8 encoding. If you use jEdit, do this to make sure you are always saving with UTF-8: From Utilities, choose Global Options, then click Loading and Saving. Choose UTF-8 from the dropdown list for Default character encoding.

Warning to Windows users: Windows Notepad says it can save UTF-8, but actually sticks two useless bytes at the beginning of any file it saves with that encoding. You can't see these useless bytes when you reopen the file in Notepad, but LargoRecipes sees them and is confused. Apparently Microsoft Word is even less helpful (but I haven't tried).

Determine the ISO codes for your language and, if applicable, the country in which that language is spoken. (Why specify the country? Well, for example, British and American English differ quite a lot, so you might want to distinguish which one you are translating for.) For example, the code for English is en and the code for Britain is GB, while the code for French is fr and for the country of France is FR. See these two sites for codes: Language codes and Country codes

Start LargoRecipes if you haven't already. After it goes through the intro screens, close it again. (This unpacks the files you need.)

In the folder where you started LargoRecipes, navigate to the lib subfolder. There you will find a file with the name IntlResourcesEnglish.0.9.1.jar. Copy this file to a convenient place, outside your LargoRecipes folder, and rename the copy to IntlResourcesFrench.0.9.1.zip (replacing French of course with whatever language you are going to be translating into).

Unzip the zip file you have copied. For instance, on Linux you type unzip IntlResourcesFrench.0.9.1.zip. You will get several new folders (this is why you copied the file to a working folder, so these new folders wouldn't clutter up LargoRecipes). The instructions below say what to do with each folder.

images. This folder contains a number of images and one subfolder called flags. Leave the images alone and go into the flags subfolder. There you will find a couple of small flag images for the USA and Britain. Pick a flag (or another image) that is a good visual symbol for your translation; it will need to be approximately the same size as the US and Britain flags already in the folder. You can find lots of such flags at Leo's Icon Archive. Rename your image in the form flag_la_CO.gif where la is the language code and CO is the country code. (See above for information about these codes.) For example, the French flag would be flag_fr_FR.gif. Save your renamed flag image in the flags subfolder and erase the British and American flags that were there to start with.
data. This folder contains one file in XML format, giving the ingredients and measures that LargoRecipes uses. Open this file and you'll see things like this:
<com.largoguidedog.RecipeEngine.Ingredient.Ingredient hasPlural="true"> <java.lang.Integer obj-name="index" value="382"/> <java.util.Vector obj-name="synonyms"> <java.lang.String valueOf="abalone"/> <java.lang.String valueOf="abalones"/> </java.util.Vector> </com.largoguidedog.RecipeEngine.Ingredient.Ingredient>
Although this looks confusing, you can ignore everything except the lines that say valueOf="XXX". Your job is to translate whatever is inside the quotation marks into your target language. So, for example, I would convert
<java.lang.String valueOf="potato"/>
into
<java.lang.String valueOf="Kartoffel"/>
for the German version of LargoRecipes. Save the file once you're done, then change its name to replace _en with your language and country code. For instance, ReferenceData_en.xml becomes ReferenceData_fr_FR.xml for the French version of LargoRecipes.

Note: If you encounter ingredients or measures that you don't know the translation for, or just don't want to use in the new language, you can leave them alone. Users will still be able to use their English names. (Don't try to delete the unwanted items from the XML file - it's too easy to make a mistake. Whatever you do, definitely don't delete any measures, as LargoRecipes relies on having each measure present.)

Note: If your language uses the ' character - as does French, for example, in phrases like "graine d'anis" - you will need to write ' everywhere you would otherwise have the ' character. For example, graine d'anis becomes graine d'anis. A simple search-and-replace through the file should take care of this for you.
META-INF. This folder contains meta-information - it tells Java what is stored in the archive. Don't change anything in it.
properties. This folder contains many files, each of which holds the prompts and messages that LargoRecipes uses. The files have names like AboutInternalFrame_en.properties. You need to translate the properties in each file - there is an easy method for this and a hard one.
- Easy method. Use a properties editor to edit the files. My favourite is the Zaval Java Resource Editor - follow the link to download this free editor. There may be other editors but I don't know about them.
- Hard method. Edit the files directly using your text editor. The contents of each file look like this:
  Title = About LargoRecipes License = License History = Version history Author = Write to the author Your job is to translate the words on the right of each equals sign into your language - but don't change the words on the left of each equals sign. For example, you'd change OpenProgram = Open to OpenProgram = Offen for the German version of LargoRecipes.
  
  Note: If your language includes any characters outside the 26 A-Z letters of English - for example, the French à, German ß, or most characters in non-Western languages like Russian or Chinese - you need to follow an extra step if you use this harder method. For each such character, replace it with \u followed by its Unicode encoding number as a 4-digit number: for instance à becomes \u0224, ß becomes \u0223, and 日 (a Chinese character that you may not be able to see if your browser isn't configured for it) becomes \u65e5. If this seems annoying, it is - but the good news is that the Zaval Java Resource Editor will take care of this for you if you use the easy method above.
Save each file as you finish translating it by either method, and then change its name to replace _en with your language and country code (see above). For example, AboutInternalFrame_en.properties becomes AboutInternalFrame_fr_FR.properties for the French version of LargoRecipes. When you are finished, the properties folder should contain only files with the suffix for your language and country.
help and startup. These folders contain HTML files used by LargoRecipes. Don't translate words inside < and > signs, like <html> and <body>, but do translate the rest of each file. Save each file when you are done, then change its name to replace the _en with your language and country code. For example, IngredientHelp_en.html becomes IngredientHelp_fr_FR.html.
credits. This folder contains one file, translation.txt. Don't translate this file; instead, give yourself credit here, for instance by writing "Translated by Hercule Poirot". Give a web site or email address, if you like. You will see the text in the About frame when you run LargoRecipes.

After completing the translation of all (or just some) of these files, it's time to try out your translation in LargoRecipes! First, zip the folders into an archive called (for instance) IntlResourcesFrench.0.9.1.zip. Be careful - don't zip a parent folder that contains all the subfolders - zip them from inside that parent. For instance, on Linux type cd FrenchLargoRecipes then


      zip IntlResourcesFrench.0.9.1.zip images data startup help META-INF properties

Change the name of the file to IntlResourcesFrench.0.9.1.jar and move it to the lib folder of your LargoRecipes installation.

Delete the data folder in your LargoRecipes installation folder. (Warning: this will erase any recipes you already have entered into LargoRecipes - you may want to back up the folder instead of deleting it, if you have recipes you care about.)

Start LargoRecipes. You'll get an error about a missing reference data file - just click Continue and LargoRecipes will load your translated data file.

Check that the items you changed are now in your language!

After you finish following these steps, please consider sending me your translated files, so I can share them with others through this web page. That way, everyone can get the benefit of your translation and enter recipes in your language!

For super-translators: Translate demo. If translating prompts and ingredients isn't enough for you, consider translating the tour of LargoRecipes (the one you get to from About..Demonstration) as well. The steps for this are similar to those above: download the English demo file from the download page, change .jar to .zip, and unzip. Then translate the HTML files as before; if you want, regenerate the sample web page and recapture the screenshots with prompts in your language. Zip it up again and replace the _en in the filename with your language and country code. Change .zip to .jar and put the resulting file in your demo directory - LargoRecipes will now load this demo if you are viewing it using your language and choose the menu item.

Chinese, Korean, and Japanese fonts: Java needs some tweaking to display these languages properly. Here's what to do:

First, you need a Unicode font that can display the characters you plan to use. (Unicode is a system of encoding characters that includes the characters from most languages, including Chinese, Korean, and Japanese.) I tested with a font called Bitstream Cyberbit that I got from this page about Chinese and Java, but I do not know much about the licensing of such fonts. Consult your operating system documentation for information about finding and installing Unicode fonts. Once your font is installed, check using your text editor that you can type and display the characters you want to see in LargoRecipes. In the remainder of this description, I will assume you are using Bitstream Cyberbit - so if you are using a different Unicode font, replace that name with the name of your Unicode font in the following.
Find the folder where you installed Java. On Windows this is normally C:\Program Files\Java\j2re1.4.2 or something similar. On Linux or (I think) Macintosh, type which java at a command prompt, navigate to the given directory, and then type cd ...
Go to the lib subfolder of the Java installation folder. Among many other things, you'll see a number of files with names that start font.properties. Find the one that is called font.properties with no other suffix, and copy it, naming the copy something like font.properties.original. This will be your backup - change it back to the original name font.properties if you want to go back to Java as you installed it.
Open the file called font.properties - the original file, not the copy you made just now - in your text editor. Find the section that looks like this:
... # Component Font Mappings # dialog.0=Arial,ANSI_CHARSET dialog.1=WingDings,SYMBOL_CHARSET dialog.2=Symbol,SYMBOL_CHARSET ... monospaced.bolditalic.0=Courier New Bold Italic,ANSI_CHARSET monospaced.bolditalic.1=WingDings,SYMBOL_CHARSET monospaced.bolditalic.2=Symbol,SYMBOL_CHARSET # Font File Names # ... Delete the entire section - all the text between the words "Component Font Mappings" and "Font File Names". Replace it with this text:
# Component Font Mappings # dialog.0=Arial,ANSI_CHARSET dialog.1=WingDings,SYMBOL_CHARSET,NEED_CONVERTED dialog.2=Symbol,SYMBOL_CHARSET,NEED_CONVERTED dialog.3=Bitstream Cyberbit dialoginput.0=Courier New,ANSI_CHARSET dialoginput.1=WingDings,SYMBOL_CHARSET,NEED_CONVERTED dialoginput.2=Symbol,SYMBOL_CHARSET,NEED_CONVERTED dialoginput.3=Bitstream Cyberbit serif.0=Times New Roman,ANSI_CHARSET serif.1=WingDings,SYMBOL_CHARSET,NEED_CONVERTED serif.2=Symbol,SYMBOL_CHARSET,NEED_CONVERTED serif.3=Bitstream Cyberbit sansserif.0=Arial,ANSI_CHARSET sansserif.1=WingDings,SYMBOL_CHARSET,NEED_CONVERTED sansserif.2=Symbol,SYMBOL_CHARSET,NEED_CONVERTED sansserif.3=Bitstream Cyberbit monospaced.0=Courier New,ANSI_CHARSET monospaced.1=WingDings,SYMBOL_CHARSET,NEED_CONVERTED monospaced.2=Symbol,SYMBOL_CHARSET,NEED_CONVERTED monospaced.3=Bitstream Cyberbit # Font File Names # Save the file.
Start LargoRecipes as normal. You should now be able to type in your characters and see them on the screen (to prove this, try typing in the title of a recipe using your language).
Of course, if you want ingredients, measures, prompts, error messages, and other displayed items to be in your language, you still have to translate them as described above.

Last updated 23 July 2003
LargoRecipes source code, program, and web site copyright 2001-3 D. Squirrel