Custom translations

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.

Part One – Kiwitrees custom translation system

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:

1. At the top, just below the “Select language” box are fields for adding a new custom translation. To use it enter the standard kiwitrees text in the left box, and your custom version in the right. (Note: see important information about the standard kiwitrees text below). Then click the save button immediately below these boxes.
2. When you save the new translation the page will refresh and that new item will appear in the “Edit existing translations” section, leaving those first boxes empty to be re-used for more translations.. This area lists each of the custom translations you have created, including the date each was last updated. The left box (standard texts) is ‘read-only’, but the right hand box can be edited if you want to make any changes at any time. There is also a delete icon to the right in case you want to completely remove a translation.
3. Once you have created and saved one or more translations visit any page they appear on. If that page was already open in your browser you will need to refresh it to see the change. Otherwise they should be immediately visible.

IMPORTANT NOTES

• The “standard kiwitrees text” is critical to this system. It must be the exact text as found the the kiwitrees code (“international English”).
• Do not attempt to translate from an already translated text, nor to assume that what you see on the screen is actually the “standard kiwitrees text”. It may have been adjusted by the display code (CSS), including such effects as conversion to all or partial capital letters.
• The translation library uses a lot of caching. So after adding your custom translations either clear the cache files (Administration > Site configuration > Clean-up data folder > delete the ‘cache’ item), or wait at least two hours. The exact location of your cache, and the time taken to automatically clear it will vary according to your setup.
• This custom translation system is not suitable for complex text strings, such as those with plural or gender-specific translations included. These must be done using the “gettext” version of the File-based custom translation system described below.
• Too many custom translations can slow your system down. If you need a lot of changes, consider whether your changes might be useful to others who use the same language. If so, you can either propose a change to the core text (English) or become a translator and the core translation for your language.
• If you have any difficulties, check the kiwitrees support forum and use that to ask for additional help.

Part Two – File-based custom translation system

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

Where to store the local language files

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.

File names and formats

The file names consist of the language code, plus an extension to indicate the format. Examples of language codes are:

• it (Italian)
• fr (French)
• de (German)
• [email protected] (Serbian in latin script)
• en_AU (Australian English)

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:

• Simplicity. You can create the files using a simple text editor or a spreadsheet.

The disadvantages of this format are:

• They cannot be used for complex translations, such as plurals (different languages have different ways of expressing plurals, depending on the number of objects), or multiple contexts (where the same word has many translations, depending on the context).
• Depending on your server configuration, it may be possible for a visitor to your site to view the contents of the file, and you may have included sensitive information in it.

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:

• Relatively simple. You can create the files using a simple text editor.

The disadvantages of this format are:

• They cannot be used for complex translations, such as plurals (different languages have different ways of expressing plurals, depending on the number of objects), or multiple contexts (where the same word has many translations, depending on the context).

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:

• It can be used for all translations, including the complex plurals and contexts. It is the format used by kiwitrees for its own translation files.
• For files containing a large number of translations, it is faster and uses less memory than the other options, as it does not need to load all translations into memory.

The disadvantages of this format are:

• It requires additional software to create the files.

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

• Whatever language you are translating into, your custom language file must always translate from the text in the core code (WT_I18N::translate(‘xxxxx’), not from any of the standard language files. If you want to see what these texts are on-screen, ensure you are viewing in en-US, rather than any other language.
• The translation library uses a lot of caching. So after adding your custom file either clear the cache files (from your system temp folder), or wait at least two hours. The exact location of your cache, and the time taken to automatically clear it will vary according to your set-up.