kivitendo/doc/languages_howto.txt @ b256bef1
| bb578fc4 | Sven Schöling | 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:
|
||||
| 8317c23b | Sven Donath | lx-office/locale/<langcode>/
|
||
| bb578fc4 | Sven Schöling | |||
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
|
||||
| 8317c23b | Sven Donath | scripts/locales.pl <langcode>
|
||
| bb578fc4 | Sven Schöling | |||
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
|
||||
| 8317c23b | Sven Donath | A "missing" file 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
|
||||
| bb578fc4 | Sven Schöling | 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
|
||||
| 8317c23b | Sven Donath | you want to provide it, it must be inlinable perl code which provides a num2text
|
||
| bb578fc4 | Sven Schöling | 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
|
||||
| 8317c23b | Sven Donath | listing of chars not suited for different file format, and provides
|
||
| bb578fc4 | Sven Schöling | 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
|
||||
| 8317c23b | Sven Donath | separated list. All entries are interpolated, so \n, \x20 and \\ all work.
|
||
| bb578fc4 | Sven Schöling | |||
After that every entry is a special char that should be translated when writing
|
||||
text into such a file.
|
||||
Example:
|
||||
[Template/XML]
|
||||
order=& < > \n
|
||||
&=&
|
||||
<=<
|
||||
>=>
|
||||
\n=<br>
|
||||
| 8317c23b | Sven Donath | Note the importance of the order in this example. Substituting < and > befor &
|
||
| bb578fc4 | Sven Schöling | would lead to $gt; become &gt;
|
||
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
|
||||
| 8317c23b | Sven Donath | its files where Linux doesn't mind that. If you want the files created with your
|
||
| bb578fc4 | Sven Schöling | 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
|
||||
| 8317c23b | Sven Donath | language package.
|
||
| bb578fc4 | Sven Schöling | |||
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.
|
||||