locale/README

   1
   2 This document describes how to add a new language translation to PhpWiki.
   3
   4 If you just want to use one of the existing language translations, see
   5 part three in 'index.php' to change the default language of your
   6 Wiki. Modify the line that sets $LANG to use the two-letter code of
   7 one of the supported languages, like this:
   8
   9     // Select your language/locale - default language "C": English
  10     // other languages available: Dutch "nl", Spanish "es", German "de",
  11     // Swedish "sv", and Italian, "it".
  12     // $LANG="C";
  13     $LANG="it";
  14
  15
  16 Phpwiki uses GNU gettext tools to provide and maintain multi-lingual
  17 messages for different languages. Even if you are already familiar
  18 with xgettext you will want to read this document to be aware of
  19 translation issues and tips specific to PhpWiki; perhaps skimming
  20 through the Makefile section.
  21
  22 PhpWiki does not require gettext support to be compiled in to PHP.  It
  23 automatically provides a pure PHP replacement in case it's not available.
  24
  25
  26 Formalities
  27 ===========
  28 The modern English language has no clear rules for differentiating
  29 between the formal and informal use of the spoken word. This both
  30 simplifies and complicates matters for translators, as many languages
  31 do still make such a distinction. For the most part, PhpWiki is written
  32 using the casual forms of messages and explanatory text--after all the
  33 WikiWikiWeb is an open and friendly place. :-)
  34
  35 However, there is no reason why translations of Wiki commands like
  36 "Edit" or "FindPages" should not be written formally. For the sake of
  37 recognition or clarity when the word function is the same as another
  38 common computer term or menu-item, if you feel it would be more
  39 effective to employ a formal variation then please do so. When the
  40 formal word is significantly longer than the informal word, make a
  41 judgement call or substitute an abbreviation, provided that it will
  42 be easily recognised.
  43
  44 Remember that a good and thorough translation is a subjective and
  45 collective process. Once people have had a chance to test-drive your
  46 newly-translated PhpWiki there will always be suggestions for
  47 reshaping and improving it.
  48
  49 Diversity and Change are part of WikiEssence. By all means don't
  50 belabour the translation process, and have some fun!
  51
  52
  53 General Steps
  54 =============
  55 The general steps to creating a new language module for PhpWiki:
  56
  57 1. Copy and rename the master template to create a new file for your
  58    language ('phpwiki.pot' => 'xx.po').
  59
  60 2. Translate all the strings in the new language file ('.po file').
  61
  62 3. Run 'make' to automatically create or update any additional files
  63    ('.po' => '.mo' => 'phpwiki.php' files).
  64
  65 4. Create translations of the content for the default pages ('pgsrc'
  66    files).
  67
  68
  69 Example
  70 =======
  71 Let's assume for example that you would like to add an Islandic
  72 translation to PhpWiki.
  73
  74
  75 Text Strings
  76 ------------
  77 Duplicate the file phpwiki.pot in the 'locale/po/' folder and name it
  78 'is.po' ('is' is the code for Islandic). Next, translate all the
  79 strings inside 'is.po' from English to Islandic. Unix Hint: Emacs has
  80 a handy "po translation mode" for you. See README.coding in the doc folder.
  81
  82 Important note about character encoding:
  83   Currently all the language files are saved using the ISO-8859-1
  84   character encoding to preserve accented characters. Make sure the text
  85   editor you use is capable of performing the appropriate Latin-1
  86   translation. Strictly speaking, ISO-8859-1 is *different* than Windows
  87   code page 1252 or MacRoman. Upon quick inspection one will notice that
  88   many of the letters do occupy the same positions in each of their'
  89   respective encoding tables, so it is easy to understand how people can
  90   make this false assumption.
  91
  92
  93 Word Reordering
  94 ---------------
  95 Different languages have different word ordering requirements. When a
  96 key word such as a person's name needs to be added to the end of a
  97 sentence in english, there is no guarantee that the same word will
  98 appear at the end of a sentence once translated to another language.
  99
 100 PhpWiki has been designed with this in mind. (Standard gettext
 101 notations like %s and %1$s, %2$s will work with PhpWiki, even though
 102 reordering of variable-substitutions is not actually part of PHP).
 103
 104 Take the following English phrase as an example. This message would be
 105 displayed in the browser when someone wants to compare two revisions
 106 of a Wiki page. The corresponding entry for the German translation for
 107 this phrase (from the file 'de.po') reads:
 108
 109     #: ../lib/diff.php:251
 110     #, c-format
 111     msgid "Differences between %s and %s of %s."
 112     msgstr "Der Unterschiedsergebnis von %3$s, zwischen %1$s und %2$s"
 113
 114 In the English version, PhpWiki will substitute the phrases "version
 115 1", "version 2" and the name of the page being compared. The
 116 placeholder '%s' indicates where text will later be substituted, while
 117 '%d' is used to indicate a number will be inserted.
 118
 119 Sentence structure of German is different than English, and this case
 120 dictates that the "page name" must come first, then followed by
 121 "Verson 1." and finally "Version 2."
 122
 123 To summarize, when the word ordering must differ, insert "1$", "2$"
 124 etc. into the middle of '%s' and repeat for each instance of '%s' in
 125 the phrase.
 126
 127 Here are a couple more examples. They are fictional but they serve to
 128 illustrate how to handle special cases, should they arise:
 129
 130
 131 #msgid "Page version '%d' named '%s' is not available."
 132 #msgstr "Xyqlmn vvvm » %s « mnqee » %d « Gvbbbnbhkkk eeek."
 133
 134 Even though %s and %d are reversed, no '1$' and '2$ are needed because
 135 one is a text string and the other is a number. The punctuation marks
 136 for this language dictate extra spacing, so this has also been accounted
 137 for in the translation (i.e. the quote marks are only for emphasis, they
 138 are not considered part of the %s placeholder).
 139
 140
 141 #msgid "Page named '%s' version '%d' written by author '%s' is not available."
 142 #msgstr "Qppn wwmoooppp '%2$s' vvvm '%1$s' mnqee '%d' Gvbbbnbhkkk eeek."
 143
 144 Name and author are reversed. No special treatment is needed for the
 145 number, because it is the only one present. The punctuation for this
 146 particular language is the same as english so it is unchanged.
 147
 148
 149 While translating the text strings if you are uncertain about the
 150 syntax, look at the '.po' files of the other languages as an
 151 example. If you are stuck or simply can't make any sense of all this,
 152 just ask one of the PhpWiki programmers on the mailing list to help
 153 out.
 154
 155 The 'phpwiki.php' files do not need to be created or edited because
 156 the Makefile will create and update these files automatically. See the
 157 'Makefile' section below.
 158
 159
 160 Default Pages
 161 -------------
 162 Most of the work will be in the translation of the default pgsrc
 163 files. As a starting point you can copy the English 'pgsrc' directory:
 164
 165     mkdir locale/is
 166     cp -rv pgsrc locale/is
 167
 168 For these 'pgsrc' files it will be sufficient to change the page names
 169 to Islandic, and maybe translate the HomePage and give it an Islandic
 170 name. Again, for anything you don't know, look at the 'nl' or 'de'
 171 versions.
 172
 173 The best approach to translating the default page content is to do all
 174 of your page editing in the web browser itself, then perform a page
 175 dump to save the pages as MIME text files.  Some of the pages are
 176 locked so you will have to log into PhpWiki as the administrator
 177 before you can edit them.
 178
 179 <FIXME>
 180    Add instructions for editing MIME headers of files before moving
 181    files into '/locale/is/pgsrc'
 182
 183  - keep modification date, page name and lock, remove author.
 184    Example:
 185     Content-Type: application/x-phpwiki;
 186       pagename= PhpWikiSystemverwalten;
 187       flags=PAGE_LOCKED;
 188       lastmodified=1008730541;
 189     Content-Transfer-Encoding: quoted-printable
 190
 191  - Make sure to rename files with accents in the page name.
 192    (e.g. "GästeBuch" => "G%E4steBuch" )
 193
 194  - Translate body text and rename plugin pages to match changes
 195    specified in the '.po' file.
 196    Example:
 197    <?plugin RecentChanges  days=3D4 show_all=3D1 show_minor=3D1?>
 198
 199 </FIXME>
 200
 201
 202 Makefile
 203 --------
 204 The Makefile calls 'xgettext' to automatically perform a number of
 205 important translation tasks:
 206
 207  * Scans through all the source code and retrieves the english
 208    strings used as text arguments, then collects and indexes them into
 209    the file 'phpwiki.pot'.
 210
 211  * Merges any new differences of the collected English text strings
 212    with similar text strings found during any previous runs of 'make',
 213    stored inside each of the translated '.po' files.
 214
 215  * Makes note of which English text strings have been added, reworded
 216    or removed. The translated strings in the '.po' files are then marked
 217    as "Fuzzy" translations for all cases where the English text has been
 218    changed. This makes it easy for translators to spot which items need
 219    to be updated. (Emacs' po mode also uses this information).
 220
 221  * The necessary '.mo' files and 'phpwiki.php' text files are
 222    synchronized and sorted according to the translated contents of the
 223    '.po' files, for each of the locale subdirectories.
 224
 225 When a new language module is added to PhpWiki, the 'Makefile' in the
 226 'locale' folder also needs to be updated. Add the two-letter gettext
 227 language code to the list of all languages known to PhpWiki, by
 228 changing the variable ALL_LINGUAS. In this example 'is' was added for
 229 Icelandic:
 230
 231         ALL_LINGUAS="nl es de sv it is"
 232
 233 To start the 'Makefile' process, change to the 'locale' directory
 234 before invoking the 'make' command:
 235
 236     cd locale
 237     make
 238
 239 Make will then automatically generate and update all the necessary
 240 files. If this step fails because you don't have the necessary
 241 software installed, then send your '.po' files to one of the PhpWiki
 242 developers who will run Makefile for you.
 243
 244
 245 HTML Templates
 246 --------------
 247 The template files do not need to be translated. As of PhpWiki 1.3 all
 248 the text strings in the html templates are cross-referenced with the
 249 translations in the '.po' files.
 250
 251 *** Note: Updating html template translations from PhpWiki 1.2 to 1.3: ***
 252
 253 The translated version of the tips for TextFormattingRules must be
 254 moved from the old html template 'editpage.html', and placed into the
 255 'pgsrc' for the default page of TextFormattingRules. A plugin now
 256 extracts this text and inserts it when editing a page in PhpWiki,
 257 rather than it being embedded within the html template itself.
 258
 259 It is suggested this paragraph would go at the top of the page. It
 260 must be in a section heading entitled "Summary" in order for the
 261 editpage template to find it. Of course you will substitute the
 262 translations for "TextFormattingRules" and "Summary", according to the
 263 wording you used for these phrases when you translated the '.po' file.
 264
 265 Refer to the English "TextFormattingRules" and German (de)
 266 "TextFormatierungsRegeln" pages to see working examples.
 267
 268
 269 Finale
 270 ======
 271 After you have finished translating, you will want to see the result
 272 of your efforts. Change the $LANG setting in 'index.php' to the
 273 two-letter code for your language.
 274
 275 Et voilà, Phpwiki should now speak Islandic!
 276
 277 If your translation was a success, you may also want to add a
 278 translation of these instructions for translating PhpWiki ;-)
 279
 280 About gettext
 281 -------------
 282 To learn more about GNU gettext and '.po' files, you may find some
 283 information at:
 284
 285     <http://www.iro.umontreal.ca/contrib/po/HTML/>
 286     <http://www.gnu.org/directory/gettext>
 287
 288 Good luck,
 289 Jan Nieuwenhuizen <janneke@gnu.org>
 290 Arno Hollosi <ahollosi@mail.com>
 291 Carsten Klapp <carstenklapp@mac.com>
 292
 293 $Id: README,v 1.4 2001-12-27 07:33:23 carstenklapp Exp $