4.4. Translations and languages

4.4.1. Introduction

[Anmerkung]Anmerkung

Dieser Abschnitt ist in Englisch geschrieben, um internationalen Übersetzern die Arbeit zu erleichtern.

This section describes how localization packages in kivitendo are built. Currently the only language fully supported is German, and since most of the internal messages are held in English the English version is usable too.

4.4.2. Character set

All files included in a language pack must use UTF-8 as their encoding.

4.4.3. File structure

The structure of locales in kivitendo is:

kivitendo/locale/<langcode>/

where <langcode> stands for an abbreviation of the language package. The builtin packages use two letter ISO 639-1 codes, but the actual name is not relevant for the program and can easily be extended to IETF language tags (i.e. "en_GB"). In fact the original language packages from SQL Ledger are named in this way.

In such a language directory the following files are recognized:

LANGUAGE

This file is mandatory.

The LANGUAGE file contains the self descripted name of the language. It should contain a native representation first, and in parenthesis an english translation after that. Example:

Deutsch (German)
all

This file is mandatory.

The central translation file. It is essentially an inline Perl script autogenerated by locales.pl. To generate it, generate the directory and the two files mentioned above, and execute the following command:

scripts/locales.pl <langcode>

Otherwise you can simply copy one of the other languages. You will be told how many are missing like this:

$ scripts/locales.pl en
English - 0.6% - 2015/2028 missing

A file named "missing" will be generated and can be edited. You can also edit the "all" file directly. Edit everything you like to fit the target language and execute locales.pl again. See how the missing words get fewer.

Num2text

Legacy code from SQL Ledger. It provides a means for numbers to be converted into natural language, like 1523 => one thousand five hundred twenty three. If you want to provide it, it must be inlinable Perl code which provides a num2text sub. If an init sub exists it will be executed first.

Only used in the check and receipt printing module.

special_chars

kivitendo comes with a lot of interfaces to different formats, some of which are rather picky with their accepted charset. The special_chars file contains a listing of chars not suited for different file format and provides substitutions. It is written in "Simple Ini" style, containing a block for every file format.

First entry should be the order of substitution for entries as a whitespace separated list. All entries are interpolated, so \n, \x20 and \\ all work.

After that every entry is a special char that should be translated when writing text into such a file.

Example:

[Template/XML]
order=& < > \n
&=&amp;
<=&lt;
>=&gt;
\n=<br>

Note the importance of the order in this example. Substituting < and > befor & would lead to $gt; become &amp;gt;

For a list of valid formats, see the German special_chars entry. As of this writing the following are recognized:

HTML
URL@HTML
Template/HTML
Template/XML
Template/LaTeX
Template/OpenDocument
filenames

The last of which is very machine dependant. Remember that a lot of characters are forbidden by some filesystems, for exmaple MS Windows doesn't like ':' in its files where Linux doesn't mind that. If you want the files created with your language pack to be portable, find all chars that could cause trouble.

missing

This file is not a part of the language package itself.

This is a file generated by scripts/locales.pl while processing your locales. It's only to have the missing entries singled out and does not belong to a language package.

lost

This file is not a part of the language package itself.

Another file generated by scripts/locales.pl. If for any reason a translation does not appear anymore and can be deleted, it gets moved here. The last 50 or so entries deleted are saved here in case you made a typo, so that you don't have to translate everything again. If a tranlsation is missing, the lost file is checked first. If you maintain a language package, you might want to keep this safe somewhere.

more/all

This subdir and file is not a part of the language package itself.

If the directory more exists and contains a file called all it will be parsed in addition to the mandatory all (see above). The file is useful if you want to change some translations for the current installation without conflicting further upgrades. The file is not autogenerated and has the same format as the all, but needs another key (more_texts). See the german translation for an example or copy the following code:

#!/usr/bin/perl
# -*- coding: utf-8; -*-
# vim: fenc=utf-8

use utf8;

# These are additional texts for custom translations.
# The format is the same as for the normal file all, only
# with another key (more_texts instead of texts).
# The file has the form of 'english text'  => 'foreign text',

$self->{more_texts} = {

  'Ship via'                    => 'Terms of delivery',
  'Shipping Point'              => 'Delivery time',
}