projekt kivitendo

Table of Contents

=================

1. What's this?

2. File Structue

  * LANGUAGE

  * charset

  * all

  * Num2text

  * special_chars

  * missing

  * lost

What's this?

============

This document describes how localization packages in Lx-Office 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.

A stub version of french is included, but not functunal at this point.

File Structure

==============

The structure of locales in Lx-Office is:

  lx-office/locale/<lnagcode>/

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

charset (encouraged)

--------------------

The charset file describes which charset a language package is written in and

applies to all other language files in the package. It is possible to write some

language packages without an explicit charset, but it is still strongly

recommended. You'll never know in what environment your language package will be

used, and neither utf-8 nor latin1 are guaranteed.

The whole content of this file is a string that can be recognized as a valid

charset encoding.

Example:

  ISO-8859-1

all (mandatory)

---------------

The central translation file. It is essentially an inline perlscript

autogenerated by locales.pl. To generate it, generate the directory and the two

files mentioned above, and execute

  scripts/locaes.pl <langcode>

or 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 "missing" file will be generated and can be edited. You can also edit the all

directly. Edit all that sounds differently in your language, and execute

locales.pl again. See how the missing words get fewer.

These three files are necessary for a localization to be working. Other files

are optional, but will have special effects:

Num2text (optional)

-------------------

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 privdes a num2text

sub. If an init sub exists, it will be executed first.

Only used in the check and receipt printing module.

special_chars

-------------

Lx-Office 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 diefferent 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

  &=&

  <=&lt;

  >=>

  \n=<br>

Note how in this example the order is important. Substituting < and > befor &

would lead to $gt; become >

For a list of valid formats, see the german special_chars entry. As of this

writing the following are recognized:

  HTML

  URL@HTML

  XUL

  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 (not part of language package)

--------------------------------------

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

languge package.

lost (not part of language package)

-----------------------------------

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.  It is not part of a language package.