X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;f=doc%2Flanguages_howto.txt;fp=doc%2Flanguages_howto.txt;h=cb4a18838062aa8001889dbc2a5ad2bd63e9435e;hb=bb578fc435b512f24dd72935796c3f8e925d7134;hp=0000000000000000000000000000000000000000;hpb=d2b14df82c100ba09806acb57ddeabdc610ff644;p=kivitendo-erp.git diff --git a/doc/languages_howto.txt b/doc/languages_howto.txt new file mode 100644 index 000000000..cb4a18838 --- /dev/null +++ b/doc/languages_howto.txt @@ -0,0 +1,170 @@ +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// + +where 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 + +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 + &=& + <=< + >=> + \n=
+ +Note how in this example the order is important. Substituting < and > befor & +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 +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. + + +