locale/README

   1
   2 Phpwiki uses GNU gettext tools to provide and maintain multi-lingual
   3 messages for different languages.
   4
   5     <http://www.gnu.org/directory/gettext>
   6
   7 This document describes how to add a new language translation to PhpWiki.
   8
   9 If you just want to use one of the existing language translations, see
  10 part three in 'index.php' to change the default language of your
  11 Wiki. Modify the line that sets $LANG to use the two-letter code of
  12 one of the supported languages, like this:
  13
  14    //  Select your language - default language "C": English
  15    // other languages available: Dutch "nl", Spanish "es", German "de"
  16    // $LANG="C";
  17    $LANG="is";
  18
  19
  20 General Steps
  21 =============
  22 The general steps to creating a new language module for PhpWiki are as
  23 follows:
  24
  25 1. Copy and rename the master template to create a new file for your
  26    language ('phpwiki.pot' => 'xx.po').
  27
  28 2. Translate all the strings in the new language file ('.po file').
  29
  30 3. Run "Make" to automatically create or update any additional files
  31    ('.po' => '.mo' => 'phpwiki.php' files).
  32
  33 4. Create translations of the content for the default pages ('pgsrc'
  34    files).
  35
  36
  37 Example
  38 =======
  39 Let's assume for example that you would like to add an Islandic
  40 translation to PhpWiki.
  41
  42
  43 Text Strings
  44 ------------
  45 Duplicate the file phpwiki.pot in the 'locale/po/' folder and name it
  46 'is.po' ('is' is the code for Islandic). Next, translate all the
  47 strings inside 'is.po' from English to Islandic. Unix Hint: Emacs has
  48 a handy "po translation mode" for you.
  49
  50 Important: Currently all the language files are saved using the
  51 ISO-8859-1 character encoding to preserve accented characters. Make
  52 sure the text editor you use is capable of the appropriate Latin-1
  53 translation. Strictly speaking, ISO-8859-1 is *different* than Windows
  54 code page 1252 or MacRoman. Upon quick inspection one will notice that
  55 many of the letters do occupy the same positions in each of their'
  56 respective encoding tables, so it is easy to understand how people
  57 have made such a false assumption.
  58
  59 <FIXME> Add a note about %s and variable reordering: %3$s, %1$s, %2$s. </FIXME>
  60
  61 Example of word-substitution-reordering from 'de.po':
  62     #: ../lib/diff.php:251
  63     #, c-format
  64     msgid "Differences between %s and %s of %s."
  65     msgstr "Der Unterschiedsergebnis von %3$s, zwischen %1$s und %2$s."
  66
  67 While translating the text strings if you are uncertain about the
  68 syntax, look at the '.po' files of the other languages as an
  69 example. The 'phpwiki.php' file does not need to be created or edited
  70 because the Makefile will create and update these files automatically
  71 (see below**).
  72
  73
  74 Default Pages
  75 -------------
  76 Most of the work will be in the translation of the default pgsrc
  77 files. As a starting point you can copy the English 'pgsrc' directory:
  78
  79     mkdir locale/is
  80     cp -rv pgsrc locale/is
  81
  82 For these 'pgsrc' files it will be sufficient to change the page names
  83 to Islandic, and maybe translate the HomePage and give it an Islandic
  84 name. Again, for anything you don't know, look at the `nl' or `de'
  85 versions.
  86
  87 The best approach to translating the default pages is to do all of
  88 your page editing in the web browser itself, then perform a page dump
  89 to save the pages as MIME text files.  Some of the pages are locked so
  90 you will have to log into PhpWiki as the administrator before you can
  91 edit them.
  92
  93 <FIXME>
  94    Add instructions for editing MIME headers of files before moving
  95    files into '/locale/is/pgsrc'
  96
  97  - keep modification date, page name and lock, remove author).
  98    Example:
  99     Content-Type: application/x-phpwiki;
 100       pagename= PhpWikiSystemverwalten;
 101       flags=PAGE_LOCKED;
 102       lastmodified=1008730541;
 103     Content-Transfer-Encoding: quoted-printable
 104
 105  - Make sure to rename files with accents in the page name.
 106    (e.g. "GästeBuch" => "G%E4steBuch" )
 107
 108  - Translate body text and rename plugin pages to match changes
 109    specified in the '.po' file.
 110    Example:
 111    <?plugin RecentChanges  days=3D4 show_all=3D1 show_minor=3D1?>
 112
 113 </FIXME>
 114
 115
 116 Makefile
 117 --------
 118 The Makefile automatically performs a number of important translation tasks:
 119
 120  * Retrieves all the English text strings used throughout the php
 121    code, then collects and indexes them into the file 'phpwiki.pot'.
 122
 123  * Merges any new differences of the collected English text strings
 124    with similar text strings found during any previous runs of 'make',
 125    stored inside each of the translated '.po' files.
 126
 127  * Makes note of which English text strings have been added, reworded
 128    or removed. The translated strings in the '.po' files are then marked
 129    as "Fuzzy" translations for all cases where the English text has been
 130    changed. This makes it easy for translators to spot which items need
 131    to be updated. (Emacs' po mode also uses this information).
 132
 133  * The necessary '.mo' files and 'phpwiki.php' text files are
 134    synchronized and sorted according to the translated contents of the
 135    '.po' files, for each of the locale subdirectories.
 136
 137 When a new language module is added to PhpWiki the 'Makefile' in the
 138 'locale' folder also needs to be updated. Add the two-letter gettext
 139 language code to the list of all languages known by PhpWiki, by
 140 changing the variable ALL_LINGUAS. In this example 'is' was added for
 141 Icelandic:
 142
 143         ALL_LINGUAS="nl es de sv it is"
 144
 145 To start the 'Makefile' process, change to the 'locale' directory
 146 before invoking the 'make' command:
 147
 148     cd locale
 149     make
 150
 151 Make will then automatically generate and update all the necessary
 152 files. If this step fails because you don't have the necessary
 153 software installed, then send your '.po' files to one of the PhpWiki
 154 developers who will run Makefile for you.
 155
 156
 157 HTML Templates
 158 --------------
 159 The template files do not need to be translated. As of PhpWiki 1.3 all
 160 the text strings have been moved out of the html templates into the
 161 '.po' files.
 162
 163 *** Note: Updating html template translations from PhpWiki 1.2 to 1.3: ***
 164
 165     The translated version of the tips for TextFormattingRules
 166     must be moved from the old html template 'editpage.html', and placed
 167     into the 'pgsrc' for the default page of TextFormattingRules. A plugin
 168     now extracts this text and inserts it when editing a page in PhpWiki,
 169     rather than putting it into the html template itself.
 170
 171 It is suggested to put the paragraph at the top of the page. It must
 172 be in a section heading entitled "Summary". Of course you will
 173 substitute the translations for "TextFormattingRules" and "Summary",
 174 according to the wording you used for these phrases when you
 175 translated the '.po' file.
 176
 177 Refer to the English "TextFormattingRules" and German (de)
 178 "TextFormatierungsRegeln" pages to see working examples.
 179
 180
 181 Finale
 182 ======
 183 After you have finished translating, you may want to check the result
 184 of your efforts. Change the $LANG setting in 'index.php' to the
 185 two-letter code for your language.
 186
 187 Et voilà, Phpwiki should now speak Islandic!
 188
 189 If your translation was a success, you may also want to add a
 190 translation of these instructions for PhpWiki ;-)
 191
 192 About gettext
 193 -------------
 194 To learn more about GNU gettext and '.po' files, you may find some
 195 information at:
 196
 197     <http://www.iro.umontreal.ca/contrib/po/HTML/>
 198     <http://www.gnu.org/directory/gettext>
 199
 200 Good luck,
 201 Jan Nieuwenhuizen <janneke@gnu.org>
 202 Arno Hollosi <ahollosi@mail.com>
 203 Carsten Klapp <carstenklapp@mac.com>
 204
 205 $Id: README,v 1.3 2001-12-27 04:25:02 carstenklapp Exp $