CSV-Import: Groß-/Kleinschreibung bei Spaltennamen ignorieren
[kivitendo-erp.git] / doc / languages_howto.txt
1 Table of Contents
2 =================
3
4 1. What's this?
5 2. File Structue
6   * LANGUAGE
7   * charset
8   * all
9   * Num2text
10   * special_chars
11   * missing
12   * lost
13
14
15 What's this?
16 ============
17
18 This document describes how localization packages in Lx-Office are built.
19 Currently the only language fully supported is german, and since most of the
20 internal messages are held in english the english version is usable too.
21
22 A stub version of french is included, but not functunal at this point.
23
24
25 File Structure
26 ==============
27
28 The structure of locales in Lx-Office is:
29
30   lx-office/locale/<langcode>/
31
32 where <langcode> stands for an abbreviation of the language package. The builtin
33 packages use two letter ISO 639-1 codes, but the actual name is not relevant for
34 the program and can easily be extended to IETF language tags (i.e.  "en_GB"). In
35 fact the original language packages from sql ledger are named in this way.
36
37 In such a language directory the following files are recognized:
38
39 LANGUAGE (mandatory)
40 --------------------
41
42 The LANGUAGE file contains the self descripted name of the language. It should
43 contain a native representation first, and in parenthesis an english
44 translation after that.
45
46 Example:
47
48   Deutsch (German)
49
50
51 charset (encouraged)
52 --------------------
53
54 The charset file describes which charset a language package is written in and
55 applies to all other language files in the package. It is possible to write some
56 language packages without an explicit charset, but it is still strongly
57 recommended. You'll never know in what environment your language package will be
58 used, and neither utf-8 nor latin1 are guaranteed.
59
60 The whole content of this file is a string that can be recognized as a valid
61 charset encoding.
62
63 Example:
64
65   ISO-8859-1
66
67
68 all (mandatory)
69 ---------------
70
71 The central translation file. It is essentially an inline perlscript
72 autogenerated by locales.pl. To generate it, generate the directory and the two
73 files mentioned above, and execute
74
75   scripts/locales.pl <langcode>
76
77 or simply copy one of the other languages. You will be told how many are missing
78 like this:
79
80   $ scripts/locales.pl en
81
82   English - 0.6% - 2015/2028 missing
83
84 A "missing" file will be generated and can be edited. You can also edit the "all" file
85 directly. Edit everything you like to fit the target language, and execute
86 locales.pl again. See how the missing words get fewer.
87
88
89
90 These three files are necessary for a localization to be working. Other files
91 are optional, but will have special effects:
92
93
94 Num2text (optional)
95 -------------------
96
97 Legacy code from sql ledger. It provides a means for numbers to be converted
98 into natural language, like 1523 => one thousand five hundred twenty three. If
99 you want to provide it, it must be inlinable perl code which provides a num2text
100 sub. If an init sub exists, it will be executed first.
101
102 Only used in the check and receipt printing module.
103
104 special_chars
105 -------------
106
107 Lx-Office comes with a lot of interfaces to different formats, some of which are
108 rather picky with their accepted charset. The special_chars file contains a
109 listing of chars not suited for different file format, and provides
110 substitutions. It is written in "Simple Ini" style, containing a block for every
111 file format.
112
113 First entry should be the order of substitution for entries as a whitespace
114 separated list. All entries are interpolated, so \n, \x20 and \\ all work.
115
116 After that every entry is a special char that should be translated when writing
117 text into such a file.
118
119 Example:
120
121   [Template/XML]
122   order=& < > \n
123   &=&amp;
124   <=&lt;
125   >=&gt;
126   \n=<br>
127
128 Note the importance of the order in this example. Substituting < and > befor &
129 would lead to $gt; become &amp;gt;
130
131 For a list of valid formats, see the german special_chars entry. As of this
132 writing the following are recognized:
133
134   HTML
135   URL@HTML
136   XUL
137   Template/HTML
138   Template/XML
139   Template/LaTeX
140   Template/OpenDocument
141   filenames
142
143 The last of which is very machine dependant. Remember that a lot of characters
144 are forbidden by some filesystems, for exmaple MS Windows doesn't like ':' in
145 its files where Linux doesn't mind that. If you want the files created with your
146 language pack to be portable, find all chars that could cause trouble.
147
148
149 missing (not part of language package)
150 --------------------------------------
151
152 This is a file generated by scripts/locales.pl while processing your locales.
153 It's only to have the missing entries singled out and does not belong to a
154 language package.
155
156
157 lost (not part of language package)
158 -----------------------------------
159
160 Another file generated by scripts/locales.pl. If for any reason a translation
161 does not appear anymore and can be deleted, it gets moved here. The last 50 or
162 so entries deleted are saved here in case you made a typo, so that you don't
163 have to translate everything again. If a tranlsation is missing, the lost file
164 is checked first. If you maintain a language package, you might want to keep
165 this safe somewhere.  It is not part of a language package.
166
167
168