di-manual/translations_po.txt

   1 Debian Installation Manual - notes for translation
   2 --------------------------------------------------
   3
   4 This file explains how to translate the manual using .po files.
   5 This is now officially supported.
   6
   7 !!! For general information on translating the manual, please see the
   8 !!! translations.txt file.
   9
  10 Note: if you happen to modify this file, please don't forget to
  11       update the trailing changelog
  12
  13 Background information
  14 ======================
  15 There are currently two toolsets that support translating XML files using .po
  16 files: KDE's poxml and po4a. We have chosen poxml as that gives better context
  17 (it does not split paragraphs) for translation.
  18 The downside of the poxml tools is that they require the .xml files to be
  19 "proper" XML. Because some of the individual files in the English
  20 original are not proper XML, we've had to "integrate" the files per chapter.
  21
  22 This means that instead of translating about 160 small files, you will be
  23 translating about 15 large files.
  24
  25 Current limitations
  26 ===================
  27 Building from PO files is currently not supported in the Sarge branch of d-i's
  28 SVN repository. This is however not a real problem as the XML files created
  29 from the PO files are used to synchronise the Sarge branch from trunk.
  30 Therefore translators should not worry about this.
  31
  32 Requirements
  33 ============
  34 The following packages need to be installed on your system:
  35 - gettext
  36 - poxml
  37 - gawk
  38
  39 If you also want to be able to build the manual, you also need to install the
  40 build dependencies listed in build/README.
  41
  42 Available tools
  43 ===============
  44 You will not be using poxml itself, but rather some scripts that call the
  45 poxml tools.
  46
  47 - ./scripts/merge_xml  : merges the small .xml files into larger files
  48 - ./scripts/update_pot : creates (new) .pot templates based on integrated
  49                          English .xml files
  50 - ./scripts/revert_pot : used to revert changes in POT files to avoid
  51                          accidental commits
  52 - ./scripts/update_po  : updates your .po files when there are changes in the
  53                          English text (the .pot templates)
  54 - ./scripts/create_xml : creates translated .xml files from the merged English
  55                          .xml files and the translated .po files
  56 - ./scripts/create_po  : used to convert an existing .xml translation to
  57                          using .po files
  58 - ./scripts/set_untranslated : used for the conversion of existing translations
  59
  60 All scripts should be run from the ./manual directory and take the language as
  61 parameter.
  62
  63
  64 Starting a new translation
  65 ==========================
  66 This procedure should only be used if there is no existing translation using
  67 XML files for your language! See the section on conversion below if you want
  68 to switch from translating XML files to using PO files.
  69
  70 The template files for the manual are available in ./po/pot, so all you need
  71 to do is create a new directory for your language (using the official ISO
  72 code for your language) and copy the .pot file you want to translate to a
  73 .po file in that directory.
  74
  75 Example for a Dutch translation:
  76   - mkdir ./po/nl
  77   - cp ./po/pot/bookinfo.pot ./po/nl/bookinfo.po
  78   - <po editor> ./po/nl/bookinfo.po
  79
  80 Use your favorite PO file editor (like kbabel) to translate the .po file.
  81 You don't need to copy all POT files straight away, just copy each one as you
  82 start translating them.
  83
  84
  85 Committing your translation
  86 ===========================
  87 The translation can be committed to d-i's SVN repository using:
  88   1. svn ci ./po/<your language> -m "<some comment describing the changes>"
  89
  90 If this is the first time you commit the translation of a file, you will need
  91 to run the 'svn add' command on the new files before you do 'svn ci'.
  92 Tip: use the commands 'svn st ' and 'svn diff' before you commit your changes
  93 to check what you are committing before you run the 'svn ci' command.
  94
  95
  96 Updating your translation
  97 =========================
  98 The PO files for your language and the templates for the manual are updated
  99 regularly when there are changes in the original English XML files.
 100 This is done during the "daily" builds (currently done by Frans Pop); you
 101 should not have to update your PO files yourself.
 102 Changed strings will be marked 'fuzzy' and new strings will be untranslated.
 103
 104 After this your PO files in the ./po directory should be updated and you can
 105 update the translation with your favorite PO file editor. To commit the
 106 changes, follow again the procedure described in the previous section.
 107
 108 To update the POT and PO files manually, use the following commands:
 109   1. svn up
 110   2. ./scripts/merge_xml en
 111   3. ./scripts/update_pot
 112   4. ./scripts/update_po <your language>
 113
 114 NOTE
 115 Doing this manually may result in SVN conflicts when you next 'svn up' with
 116 the repository. The preferred method is to just wait until your PO files are
 117 updated for you.
 118
 119
 120 Building the manual yourself
 121 ============================
 122 If you want to build a HTML version (or other format) of the manual yourself,
 123 you will have to generate the XML for your language before you can run the
 124 buildone.sh script. This can be useful, for example to debug build errors.
 125
 126 Use the following commands:
 127   1. ./scripts/merge_xml en
 128   2. ./scripts/update_pot
 129   3. ./scripts/update_po <your language>
 130   4. ./scripts/revert_pot
 131   5. ./scripts/create_xml <your language>
 132
 133 Steps 2 and 3 are necessary because the English XML files may have been
 134 updated since the last daily build of the manual, so the POT files and your
 135 PO files may be out-of-date. Step 4 makes sure you do not accidentally
 136 update the POT files in the repository. They are not needed to create the
 137 XML files or build the manual.
 138
 139 After that you can run the buildone.sh script as documented in the README in
 140 the ./build directory. If you run buildone.sh without first generating the
 141 XML files, you will either get an error message "unknown language" or build
 142 from an outdated version of the XML files.
 143
 144
 145 Converting an existing translation from .xml files to .po files
 146 ===============================================================
 147 It is possible to convert an existing translation of the manual (where the
 148 individual XML files have been translated) to using PO files.
 149 There are two important conditions:
 150 - the translation must be up-to-date with the English XML files;
 151 - the translation must have same structure as the English XML files (i.e.
 152   the translation must have the same chapters, sections, paragraphs, tables,
 153   examples, etc; you can have no 'extra' paragraphs in your translation).
 154
 155 The first condition does not mean that everything needs to be translated!
 156
 157 The conversion is fairly difficult and some checks need to be done after some
 158 of the steps. Full instructions for converting a translation can be found at:
 159 http://lists.debian.org/debian-boot/2007/07/msg00814.html.
 160
 161 Note that conversions are only done rarely and that the script used may
 162 need updating.
 163
 164 --------------------------------------------------------------------------
 165
 166 If you find any errors in this file, please fix them.
 167
 168 --------------------------------------------------------------------------
 169 Changelog:
 170
 171 2007-07-31 Frans Pop
 172  - Add link to full conversion instructions
 173
 174 2005-04-19 Frans Pop
 175  - Finally rewrite this file following official implementation of PO file
 176    translation over a month ago...
 177  - Reflect the changed file structure in the ./po directory
 178
 179 2005-02-15 Frans Pop
 180  - Corrected the location where generated XML files are written
 181
 182 2005-02-14 Frans Pop
 183  - Corrected an error in the name of one script
 184  - Clarified the difference between starting a new translation and
 185    converting an existing one
 186
 187 2005-02-12 Frans Pop
 188  - First version