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/<lnagcode>/
  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/locaes.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
  85 directly. Edit all that sounds differently in your language, and execute
  86 locales.pl again. See how the missing words get fewer.
  87
  88
  89
  90
  91
  92 These three files are necessary for a localization to be working. Other files
  93 are optional, but will have special effects:
  94
  95
  96 Num2text (optional)
  97 -------------------
  98
  99 Legacy code from sql ledger. It provides a means for numbers to be converted
 100 into natural language, like 1523 => one thousand five hundred twenty three. If
 101 you want to provide it, it must be inlinable perl code which privdes a num2text
 102 sub. If an init sub exists, it will be executed first.
 103
 104 Only used in the check and receipt printing module.
 105
 106 special_chars
 107 -------------
 108
 109 Lx-Office comes with a lot of interfaces to different formats, some of which are
 110 rather picky with their accepted charset. The special_chars file contains a
 111 listing of chars not suited for diefferent file format, and provides
 112 substitutions. It is written in "Simple Ini" style, containing a block for every
 113 file format.
 114
 115 First entry should be the order of substitution for entries as a whitespace
 116 separated list. all entries are interpolated, so \n, \x20 and \\ all work.
 117
 118 After that every entry is a special char that should be translated when writing
 119 text into such a file.
 120
 121 Example:
 122
 123   [Template/XML]
 124   order=& < > \n
 125   &=&amp;
 126   <=&lt;
 127   >=&gt;
 128   \n=<br>
 129
 130 Note how in this example the order is important. Substituting < and > befor &
 131 would lead to $gt; become &amp;gt;
 132
 133 For a list of valid formats, see the german special_chars entry. As of this
 134 writing the following are recognized:
 135
 136   HTML
 137   URL@HTML
 138   XUL
 139   Template/HTML
 140   Template/XML
 141   Template/LaTeX
 142   Template/OpenDocument
 143   filenames
 144
 145 The last of which is very machine dependant. Remember that a lot of characters
 146 are forbidden by some filesystems, for exmaple MS Windows doesn't like ':' in
 147 its files where linux doesn't mind that. If you want the files created with your
 148 language pack to be portable, find all chars that could cause trouble.
 149
 150
 151 missing (not part of language package)
 152 --------------------------------------
 153
 154 This is a file generated by scripts/locales.pl while processing your locales.
 155 It's only to have the missing entries singled out and does not belong to a
 156 languge package.
 157
 158
 159 lost (not part of language package)
 160 -----------------------------------
 161
 162 Another file generated by scripts/locales.pl. If for any reason a translation
 163 does not appear anymore and can be deleted, it gets moved here. The last 50 or
 164 so entries deleted are saved here in case you made a typo, so that you don't
 165 have to translate everything again. If a tranlsation is missing, the lost file
 166 is checked first. If you maintain a language package, you might want to keep
 167 this safe somewhere.  It is not part of a language package.
 168
 169
 170