Internationalization of Haskell programs using gettext
The approach I'll talk about is based on GNU gettext utility. All my experience on this utility is taken from internationalizing Python applications. So I adapted this experience to the Haskell world.
Prepare program for internationalization
Let's start with an example. Suppose that we want to make the following program multilingual:
module Main where
import IO
main = do
putStrLn "Please enter your name:"
name <- getLine
putStrLn $ "Hello, " ++ name ++ ", how are you?"
Using these recomendations, prepare strings and wrap them to some 'translation' function '__':
module Main where
import IO
import Text.Printf
__ = id
main = do
putStrLn (__ "Please enter your name:")
name <- getLine
printf (__ "Hello, %s, how are you?") name
We will return to the definition of '__' a bit later; for now we will leave the function empty (id
).
Translate
The next step is to generate a POT file (a template which contains all strings to needed to be translated). For Python, C, C++ and Scheme there is the xgettext utility, but it doesn't support Haskell. So I created simple utility, that does the same thing for haskell files --- hgettext. You could find it on Hackage.
Now, from the directory that contains your project, run this command:
hgettext -k __ -o messages.pot Main.hs
It will gather all strings containing the function '__' from the Main.hs and write everything to messages.pot.
Now look at the resulting pot file:
# Translation file msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2009-01-13 06:05-0800\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: Main.hs:0 msgid "Please enter your name:" msgstr "" #: Main.hs:0 msgid "Hello, %s, how are you?\n" msgstr ""
We are interested in the last part of this file -- the parts beginning with #: Main.hs:.... Each is followed by a pair of lines beginning with msgid and msgstr. msgid is the original text from the code, and msgstr is the translated string. Each language should have its own translation file. I will create two translations: German and English.
To create a PO file for specific locale we should use the msginit utility.
To generate the German translation template run:
msginit --input=messages.pot --locale=de.UTF-8
And for English translations run:
msginit --input=messages.pot --locale=en.UTF-8
If we look at the generated files (en.po and de.po), we will see that English translation is completely filled, only the German PO file needs to be edited. So we fill it with following strings:
#: Main.hs:0 msgid "Please enter your name:" msgstr "Wie heißen Sie?" #: Main.hs:0 msgid "Hello, %s, how are you?\n" msgstr "Hallo, %s, wie geht es Ihnen?\n"
Install translation files
Now we have to create directories where these translations should be placed. Originally all translation files are placed in the folder /usr/share/locale/ , but you are free to select a different place. Run:
mkdir -p {de,en}/LC_MESSAGES
This will create two sub-directories 'de' and 'en', each containing LC_MESSAGES, in the current directory. Now we use the msgfmt tool to encode our po files to mo files (binary translation files):
msgfmt --output-file=en/LC_MESSAGES/hello.mo en.po msgfmt --output-file=de/LC_MESSAGES/hello.mo de.po
Turn on internationalization in the code
Ok, now the preparatory tasks are done. The final step is to modify the code to support the internationalization:
module Main where
import IO
import Text.I18N.GetText
import System.Locale.SetLocale
import System.IO.Unsafe
__ :: String -> String
__ = unsafePerformIO . getText
main = do
setLocale LC_ALL (Just "")
bindTextDomain "hello" (Just ".")
textDomain (Just "hello")
putStrLn (__ "Please enter your name:")
name <- getLine
printf (__ "Hello, %s, how are you?\n") name
Here we added three initialization strings:
setLocale LC_ALL (Just "")
bindTextDomain "hello" (Just ".")
textDomain (Just "hello")
You'll have to download the setlocale package to enable the first function: it sets the current locale to the default value. The next two functions tell gettext to take the "hello.mo" message file from the locale directory (I set it to ".", but in general case, this directory should be passed from the package configuration).
The final step is to define the function '__'. It simply calls getText
from the module Text.I18N.GetText
. Its type is String -> IO String
so I used unsafePerformIO
to make it simpler the.
Run and test the program
Now you can build and try the program in different locales:
user> ghc --make Main.hs [1 of 1] Compiling Main ( Main.hs, Main.o ) Linking Main ... user> LOCALE=en_US.UTF-8 ./Main Please enter your name: Bond Hello, Bond, how are you? user> LOCALE=de_DE.UTF-8 ./Main Wie heißen Sie? Bond Hallo, Bond, wie geht es Ihnen? user>
Distribute internationalized cabal package
From the version 0.1.5 of hgettext package, there is included module, that teaches Cabal to install language files.
Create directory structure
Currently we have following files:
Main.hs
- The `hello` program itself.
messages.pot
- Template file, which contain all strings to be translated. This file should be included into the distribution to allow other users to generate translation file for their language.
en.po
,de.po
- Translations to the English and German languages. These files should be installed to the `locale` folder and our program has to be able to find them (has to know where they going to be installed)
Any other files could be generated from the previous, so they shouldn't be included to the distribution package.
Let's create the directory structure for our project. This is simple project, so directory structure should be simple too. Here it is:
hello\ | |-po\ | | | |-messages.pot | |-en.po | |-de.po | |-src\ | |-Main.hs
Create install script
In order to create a cabal package, we have to add only two files. The first is hello.cabal:
Name: hello Version: 0.1.3 Cabal-Version: >= 1.6 License: BSD3 Author: James Bond Maintainer: James.Bond@MI6.bi Copyright: 2009 James Bond Category: Hello Synopsis: Internationalized Hello sample Build-Type: Custom Extra-Source-Files: po/*.po po/*.pot x-gettext-po-files: po/*.po x-gettext-domain-name: hs-hello Executable hello Main-Is: Main.hs Hs-Source-Dirs: src Build-Depends: base,hgettext >= 0.1.5, setlocale
This is the standard .cabal file, but there we added two more lines:
x-gettext-po-files
- Tells cabal where ar PO files to install
x-gettext-domain-name
- Sets the domain name, under which files will be installed
For other details see documentation for hgettext Distribution.Simple.I18N.GetText
module.
Note that we also enumerated *.po files in the extra-source-files section to add them to the distribution package, and specified Build-type: Custom.
The second file to create --- Setup.hs:
import Distribution.Simple.I18N.GetText
main = gettextDefaultMain
The gettextDefaultMain
function substitutes the defaultMain function, but also adds several install hooks to the cabal package, to handle internationalization stuff.
Update the program code
So our installer knows where to put the *.po files and the domain name for them. Our code should know it too --- to make proper initialization. It is not Haskell way to duplicate same information twice, so let's modify the code to get the initialization parameters directly from the installer:
module Main where
import Text.Printf
import Text.I18N.GetText
import System.Locale.SetLocale
import System.IO.Unsafe
__ :: String -> String
__ = unsafePerformIO . getText
main = do
setLocale LC_ALL (Just "")
bindTextDomain __MESSAGE_CATALOG_DOMAIN__ (Just __MESSAGE_CATALOG_DIR__)
textDomain __MESSAGE_CATALOG_DOMAIN__
putStrLn (__ "Please enter your name:")
name <- getLine
printf (__ "Hello, %s, how are you?\n") name
So, the only lines were changed are:
bindTextDomain __MESSAGE_CATALOG_DOMAIN__ (Just __MESSAGE_CATALOG_DIR__)
textDomain __MESSAGE_CATALOG_DOMAIN__
Nice. __MESSAGE_CATALOG_DOMAIN__
and __MESSAGE_CATALOG_DIR__
are macro definitions, whose hold configured strings from the Cabal.
Build, install and run
Now you could configure, build and install newly created package by invoking commands:
runhaskell Setup.hs configure runhaskell Setup.hs build runhaskell Setup.hs install
And test it:
user> LOCALE=en_US.UTF-8 hello Please enter your name: Bond Hello, Bond, how are you? user> LOCALE=de_DE.UTF-8 hello Wie heißen Sie? Bond Hallo, Bond, wie geht es Ihnen? user>