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!

LargoRecipes running in French

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.

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).

The text editor I use is jEdit but I'm sure there are many others equally good. You can download JEdit by clicking the link. It is free and written in Java, so it should work on your operating system.

Whichever editor you choose, use it to edit all the files mentioned below (except possibly the properties files - see next paragraph), 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.

JEdit - a free editor that handles encodings properly

For editing properties files, consider obtaining a properties editor. As I describe below, such an editor makes it much easier to include non-English characters in your translation.

The editors I am familiar with are Zaval Java Resource Editor and Attesoro, but there may be others. Again, these editors are free and written in Java, so you should be able to use them on any modern computer.

Zaval Java Resource Editor - a free properties editor

Attesoro - another free properties editor

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

Getting the files to translate

Download, install, and start LargoRecipes if you haven't already. After it goes through the intro screens, close it again. (This unpacks the files you will 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.

Translating the files

Now we describe, for each folder in the zip file, how to translate the files in it.

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.

Note: Your language may differ from English by having one word for both singular and plural, where English has two. For example, consider the ingredient "abalone" above. In Flooglish (a language I just made up), we say "1 enolaba" and "2 enolaba" - the singular and plural are the same. So to translate the ingredient above, we change the text like this:
<com.largoguidedog.RecipeEngine.Ingredient.Ingredient hasPlural="false"> <java.lang.Integer obj-name="index" value="382"/> <java.util.Vector obj-name="synonyms"> <java.lang.String valueOf="enolaba"/> </java.util.Vector> </com.largoguidedog.RecipeEngine.Ingredient.Ingredient>
The two changes are to change true to false in the second line and to include only one line with enolaba in it. The reverse may also be true - your language has two words where English has one. In this case, reverse the changes - change false to true and include two lines for your language's two words.

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 favourites are the Zaval Java Resource Editor or Attesoro - follow the links to download either of these free editors. 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 either of the resource editors mentioned above 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.

Packaging the files

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 credits images data startup help META-INF properties

Zipping the files on Windows

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.)

Make sure your locale is set to the language and country you have just translated for. On each operating system, "locale" means something different. On Windows 2000, you click Start, then Settings, then Control Panel, then Regional Options; then you pick the right locale and click OK. For other operating systems, consult your documentation to learn how to pick the locale you want.

Setting the locale on Windows

Start LargoRecipes. You'll get an error about a missing reference data file - just click Continue and LargoRecipes will load your translated data file. Now check that the items you changed are 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 2 August 2003
LargoRecipes source code, program, and web site copyright 2001-3 D. Squirrel