Kleines HowTo wie man die locales jetzt erstellt.

diff --git a/doc/languages_howto.txt b/doc/languages_howto.txt
new file mode 100644 (file)
index 0000000..cb4a188
--- /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/<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
+  &=&amp;
+  <=&lt;
+  >=&gt;
+  \n=<br>
+
+Note how in this example the order is important. 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
+  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.
+
+
+