Kiwitrees is written in English, and uses English internally. The GEDCOM file format also uses English keywords and identifiers. But since human beings speak a variety of languages, we use translation files to convert text into each language. The translation files are stored in the language/ directory.
Note that we also have translations into the regional variants of English. Hence we have separate translations for “British English” and “American English”.
This FAQ is in two parts. The first is a description of kiwitrees’ unique method of customising standard texts. It happens entirely in the kiwitrees administration pages (Administration > Site administration > Custom translations) and requires no programming skills. The second part describes the language file system carried over from webtrees. For backwards compatibility, and to cater for more complex language strings this remains in place. You can even use both systems if you wish.
When you open the page Administration > Site administration > Custom translations you will first see just an option to choose a language. The choice is from any of the languages your site is configured to use. Choose the one you want to produce a custom translation in.
The page will now refresh and display one or two additional sections:
The system of custom translations used by kiwitrees, and transferred over to kiwitrees uses language files to store custom translations. They can be any one of three types, depending on the complexity of the text to be translated and the your own preferences. The file types are csv, php and ‘gettext’ (.mo).
You should create a subdirectory “language” in the kiwitrees data directory. i.e. data/language/. If you have moved the data directory outside the webserver’s document root, then it should be placed in your new, private data directory.
The file names consist of the language code, plus an extension to indicate the format. Examples of language codes are:
Three formats can be used, and these are described below. The translations are always from English to the target language.
Note that translations are always case-sensitive, so that “Hello” is translated differently to “hello”.
CSV format
The simplest format is CSV. Although CSV stands for “comma separated values”, we actually use semicolons instead of commas, and all text must be surrounded by double quotes. Here is an example of a CSV file for British English, which would be called data/language/en_GB.csv.
"yes";"certainly" "no";"perhaps not"
This would cause the word “yes” to be replaced with “certainly”, throughout the program. To include a double quote in the text, precede it with a backslash “\”.
The advantages of this format are:
The disadvantages of this format are:
PHP format
The second format uses a simple PHP script to create an array of translations. As well as the translations, the file contains a simple check, to prevent visitors to your site from accessing the data. Here is an example of a PHP file for American English, which would be called data/language/en_US.php. To include a single quote in the text, precede it with a backslash “\”.
<?php if (!defined('WT_KIWITREES')) { header('HTTP/1.0 403 Forbidden'); exit; } return array( 'yes'=>'for sure!', 'no'=>'no way!' );
It is important that there are no blank lines or spaces before the initial is optional – so we don’t include it.
The advantages of this format are:
The disadvantages of this format are:
Gettext format
The third format is called gettext. Gettext is an open-source, industry-standard, library for translations. Each language requires two files. There is a PO file, which contains human-readable text. Although you *can* edit these with text editors, it is common to use a dedicated “PO editor”. POEdit is a common tool for this, although it has a number of limitations, and we recommend Better PO Editor, which was written by one of the webtrees developers, Michele Locati. The PO file needs to be converted into a MO file, which is a machine-readable, compressed version of the same file. But you may need to take the binary MO file in the release and convert it back to a PO file in order to edit it with the Better PO Editor. Only POEdit has the msgunfmt executable to do this reverse conversion. So you may need both tools.
Here is an example of a PO file for American English, which converts certain Jewish terms to Ashkenazi spellings. The file would be called en_US.po and you would need to convert it to a .mo file, which would be called data/language/en_US.mo. Note that it includes several context-sensitive translations, where we can have different translations for the same English text.
"Project-Id-Version: kiwitrees\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=n != 1;\n" "X-Poedit-Language: en\n" "X-Poedit-Country: US\n" "X-Poedit-SourceCharset: utf-8\n" msgctxt "NOMINATIVE" msgid "Heshvan" msgstr "Cheshvan" msgctxt "NOMINATIVE" msgid "Tevet" msgstr "Teves" msgctxt "GENITIVE" msgid "Heshvan" msgstr "Cheshvan" msgctxt "GENITIVE" msgid "Tevet" msgstr "Teves" msgctxt "LOCATIVE" msgid "Heshvan" msgstr "Cheshvan" msgctxt "LOCATIVE" msgid "Tevet" msgstr "Teves" msgctxt "INSTRUMENTAL" msgid "Heshvan" msgstr "Cheshvan" msgctxt "INSTRUMENTAL" msgid "Tevet" msgstr "Teves" msgid "Heshvan" msgstr "Cheshvan" msgid "Tevet" msgstr "Teves" msgid "Bat mitzvah" msgstr "Bas mitzvah" msgid "Date of bat mitzvah" msgstr "Date of bas mitzva" msgid "Place of bat mitzvah" msgstr "Place of bas mitzvah" msgid "Source for bat mitzvah" msgstr "Source for bas mitzvah"
The advantages of this format are:
The disadvantages of this format are:
Character encoding
Files should be saved in UTF8 encoding, rather than ISO-8859, latin etc. You should be especially careful with some text editors, as they often start the file with an invisible character (called a Byte-Order-Mark). If, after installing your file, you get an error of the form “Headers already sent”, you have most likely included a BOM character.
General notes
Have your say!
You must be logged in to post a comment.