2 This document describes how to add a new language translation to PhpWiki.
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:
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".
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.
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.
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. :-)
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
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.
49 Diversity and Change are part of WikiEssence. By all means don't
50 belabour the translation process, and have some fun!
55 The general steps to creating a new language module for PhpWiki:
57 1. Copy and rename the master template to create a new file for your
58 language ('phpwiki.pot' => 'xx.po').
60 2. Translate all the strings in the new language file ('.po file').
62 3. Run 'make' to automatically create or update any additional files
63 ('.po' => '.mo' => 'phpwiki.php' files).
65 4. Create translations of the content for the default pages ('pgsrc'
71 Let's assume for example that you would like to add an Islandic
72 translation to PhpWiki.
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.
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.
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.
100 PhpWiki has been designed with this in mind. (Standard printf
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 (The printf(3) manual page on your system may be of some help.)
106 Take the following English phrase as an example. This message would be
107 displayed in the browser when someone wants to compare two revisions
108 of a Wiki page. The corresponding entry for the German translation for
109 this phrase (from the file 'de.po') reads:
111 #: ../lib/diff.php:251
113 msgid "Differences between %s and %s of %s."
114 msgstr "Der Unterschiedsergebnis von %3$s, zwischen %1$s und %2$s"
116 In the English version, PhpWiki will substitute the phrases "version
117 1", "version 2" and the name of the page being compared. The
118 placeholder '%s' indicates where text will later be substituted, while
119 '%d' is used to indicate a number will be inserted.
121 Sentence structure of German is different than English, and this case
122 dictates that the "page name" must come first, then followed by
123 "Verson 1." and finally "Version 2."
125 To summarize, when the word ordering must differ, insert "1$", "2$"
126 etc. into the middle of '%s' and repeat for each instance of '%s' in
127 the phrase. If you use this "$" notation, you must use it for each
128 of the the format specifications within the string.
130 Here are a couple more examples. They are fictional but they serve to
131 illustrate how to handle special cases, should they arise:
134 #msgid "Page version '%d' named '%s' is not available."
135 #msgstr "Xyqlmn vvvm » %2$s « mnqee » %1$d « Gvbbbnbhkkk eeek."
137 The %s and %d are reversed, so '2$' and '1$' have been used to
138 indicate the new ordering. The punctuation marks for this language
139 dictate extra spacing, so this has also been accounted for in the
140 translation (i.e. the quote marks are only for emphasis, they are not
141 considered part of the %s placeholder).
144 #msgid "Page named '%s' version '%d' written by author '%s' is not available."
145 #msgstr "Qppn wwmoooppp '%3$s' vvvm '%1$s' mnqee '%2$d' Gvbbbnbhkkk eeek."
147 Name and author are reversed. Even though the position of the number
148 ('%d') isn't changed, still it must be changed to '%2$d' --- if you
149 use a '$' on one of the format specifiers you must use it on all of
150 them. The punctuation for this particular language is the same as
151 english so it is unchanged.
154 While translating the text strings if you are uncertain about the
155 syntax, look at the '.po' files of the other languages as an
156 example. If you are stuck or simply can't make any sense of all this,
157 just ask one of the PhpWiki programmers on the mailing list to help
160 The 'phpwiki.php' files do not need to be created or edited because
161 the Makefile will create and update these files automatically. See the
162 'Makefile' section below.
167 Most of the work will be in the translation of the default pgsrc
168 files. As a starting point you can copy the English 'pgsrc' directory:
171 cp -rv pgsrc locale/is
173 For these 'pgsrc' files it will be sufficient to change the page names
174 to Islandic, and maybe translate the HomePage and give it an Islandic
175 name. Again, for anything you don't know, look at the 'nl' or 'de'
178 The best approach to translating the default page content is to do all
179 of your page editing in the web browser itself, then perform a page
180 dump to save the pages as MIME text files. Some of the pages are
181 locked so you will have to log into PhpWiki as the administrator
182 before you can edit them.
185 Add instructions for editing MIME headers of files before moving
186 files into '/locale/is/pgsrc'
188 - keep modification date, page name and lock, remove author.
190 Content-Type: application/x-phpwiki;
191 pagename= PhpWikiSystemverwalten;
193 lastmodified=1008730541;
194 Content-Transfer-Encoding: quoted-printable
196 - Make sure to rename files with accents in the page name.
197 (e.g. "GästeBuch" => "G%E4steBuch" )
199 - Translate body text and rename plugin pages to match changes
200 specified in the '.po' file.
202 <?plugin RecentChanges days=3D4 show_all=3D1 show_minor=3D1?>
209 The Makefile calls 'xgettext' to automatically perform a number of
210 important translation tasks:
212 * Scans through all the source code and retrieves the english
213 strings used as text arguments, then collects and indexes them into
214 the file 'phpwiki.pot'.
216 * Merges any new differences of the collected English text strings
217 with similar text strings found during any previous runs of 'make',
218 stored inside each of the translated '.po' files.
220 * Makes note of which English text strings have been added, reworded
221 or removed. The translated strings in the '.po' files are then marked
222 as "Fuzzy" translations for all cases where the English text has been
223 changed. This makes it easy for translators to spot which items need
224 to be updated. (Emacs' po mode also uses this information).
226 * The necessary '.mo' files and 'phpwiki.php' text files are
227 synchronized and sorted according to the translated contents of the
228 '.po' files, for each of the locale subdirectories.
230 When a new language module is added to PhpWiki, the 'Makefile' in the
231 'locale' folder also needs to be updated. The process
233 0. Change into the locale directory (if you're not already there.)
235 1. If there isn't one alreayd, Create a new .po (in the po/ subdirectory)
236 for your translations:
238 cp po/phpwiki.pot po/xx.po
240 where 'xx' should be the two letter character code for the language
241 you are translating to.
243 2. If you've created a new .po file (or if there are new .php source files
244 containing translatable strings,) update the Makefile:
248 3. To make sure the list of translatable strings in the .po is in sync
249 with the actual php source code:
253 4. Edit the translations in the .po file. If you have emacs available,
254 emacs' po-mode is very helpful when doing this.
256 5. To update the compiled translation (.mo) files:
260 Make will then automatically generate and update all the necessary
261 files. If this step fails because you don't have the necessary
262 software installed, then send your '.po' files to one of the PhpWiki
263 developers who will run Makefile for you.
268 The template files do not need to be translated. As of PhpWiki 1.3 all
269 the text strings in the html templates are cross-referenced with the
270 translations in the '.po' files.
272 *** Note: Updating html template translations from PhpWiki 1.2 to 1.3: ***
274 The translated version of the tips for TextFormattingRules must be
275 moved from the old html template 'editpage.html', and placed into the
276 'pgsrc' for the default page of TextFormattingRules. A plugin now
277 extracts this text and inserts it when editing a page in PhpWiki,
278 rather than it being embedded within the html template itself.
280 It is suggested this paragraph would go at the top of the page. It
281 must be in a section heading entitled "Summary" in order for the
282 editpage template to find it. Of course you will substitute the
283 translations for "TextFormattingRules" and "Summary", according to the
284 wording you used for these phrases when you translated the '.po' file.
286 Refer to the English "TextFormattingRules" and German (de)
287 "TextFormatierungsRegeln" pages to see working examples.
292 After you have finished translating, you will want to see the result
293 of your efforts. Change the $LANG setting in 'index.php' to the
294 two-letter code for your language.
296 Et voilà, Phpwiki should now speak Islandic!
298 If your translation was a success, you may also want to add a
299 translation of these instructions for translating PhpWiki ;-)
303 To learn more about GNU gettext and '.po' files, you may find some
306 <http://www.iro.umontreal.ca/contrib/po/HTML/>
307 <http://www.gnu.org/directory/gettext>
310 Jan Nieuwenhuizen <janneke@gnu.org>
311 Arno Hollosi <ahollosi@mail.com>
312 Carsten Klapp <carstenklapp@mac.com>
314 $Id: README,v 1.6 2002-01-13 22:43:08 dairiki Exp $