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 Four in 'config/config.ini' for the DEFAULT_LANGUAGE or your special
6 starter script (wiki or index.php) to change the current or default language
7 of your Wiki. Modify or add a line that sets $LANG to use the two-letter
8 code of one of the supported languages, like this:
10 // Select your language/locale - default language "en": English
11 // English "en" (English - HomePage)
12 // Dutch "nl" (Nederlands - ThuisPagina)
13 // Spanish "es" (Español - PáginaPrincipal)
14 // French "fr" (Français - PageAccueil))
15 // German "de" (Deutsch - StartSeite)
16 // Swedish "sv" (Svenska - Framsida)
17 // Italian "it" (Italiano - PaginaPrincipale)
18 // Japanese "ja" (Japanese - ホームページ)
19 // Chinese "zh" (Chinese - 首頁)
22 Phpwiki uses the DEFAULT_LANGUAGE internally, when no $GLOBALS['LANG'] is given.
23 With certain starter script which set $LANG you can easily provide a multi-lingual wiki.
24 For convenience provide some InterWikiMap entries for easier switching to the other
25 languages then. See http://phpwiki.org/MultiLingualWiki
27 Phpwiki uses GNU gettext tools to provide and maintain multi-lingual
28 messages for different languages. Even if you are already familiar
29 with xgettext you will want to read this document to be aware of
30 translation issues and tips specific to PhpWiki; perhaps skimming
31 through the Makefile section.
33 PhpWiki does not require gettext support to be compiled in to PHP. It
34 automatically provides a pure PHP replacement in case it's not
40 The modern English language has no clear rules for differentiating
41 between the formal and informal use of the spoken word. This both
42 simplifies and complicates matters for translators, as many languages
43 do still make such a distinction. For the most part, PhpWiki is written
44 using the casual forms of messages and explanatory text--after all the
45 WikiWikiWeb is an open and friendly place. :-)
47 However, there is no reason why translations of Wiki commands like
48 "Edit" or "FindPages" should not be written formally. For the sake of
49 recognition or clarity when the word function is the same as another
50 common computer term or menu-item, if you feel it would be more
51 effective to employ a formal variation then please do so. When the
52 formal word is significantly longer than the informal word, make a
53 judgement call or substitute an abbreviation, provided that it will
56 Remember that a good and thorough translation is a subjective and
57 collective process. Once people have had a chance to test-drive your
58 newly-translated PhpWiki there will always be suggestions for
59 reshaping and improving it.
61 Diversity and Change are part of WikiEssence. By all means don't
62 belabour the translation process, and have some fun!
67 The general steps to creating a new language module for PhpWiki:
69 1. Copy and rename the master template to create a new file for your
70 language ('phpwiki.pot' => 'xx.po').
72 2. Translate all the strings in the new language file ('.po file').
73 Empty strings will be kept in english.
75 3. Run 'make' to automatically create or update any additional files
76 ('.po' => '.mo' files).
78 4. Create translations of the content for the default pages ('pgsrc'
84 Let's assume for example that you would like to add an Islandic
85 translation to PhpWiki.
90 Duplicate the file phpwiki.pot in the 'locale/po/' folder and name it
91 'is.po' ('is' is the code for Islandic). Next, translate all the
92 strings inside 'is.po' from English to Islandic. Unix Hint: Emacs has
93 a handy "po translation mode" for you. See README.coding in the doc folder.
99 All language files are saved using the UTF-8 character encoding to
100 preserve accented characters. Make sure the text editor you use is
101 capable of handling UTF-8 text.
105 Different languages have different word ordering requirements. When a
106 key word such as a person's name needs to be added to the end of a
107 sentence in english, there is no guarantee that the same word will
108 appear at the end of a sentence once translated to another language.
110 PhpWiki has been designed with this in mind. (Standard printf
111 notations like %s and %1$s, %2$s will work with PhpWiki, even though
112 reordering of variable-substitutions is not actually part of PHP).
113 (The printf(3) manual page on your system may be of some help.)
116 Take the following English phrase as an example. This message would be
117 displayed in the browser when someone wants to compare two revisions
118 of a Wiki page. The corresponding entry for the German translation for
119 this phrase (from the file 'de.po') reads:
121 #: ../lib/diff.php:251
123 msgid "Differences between %s and %s of %s."
124 msgstr "Der Unterschiedsergebnis von %3$s, zwischen %1$s und %2$s"
126 In the English version, PhpWiki will substitute the phrases "version
127 1", "version 2" and the name of the page being compared. The
128 placeholder '%s' indicates where text will later be substituted, while
129 '%d' is used to indicate a number will be inserted.
131 Sentence structure of German is different than English, and this case
132 dictates that the "page name" must come first, then followed by
133 "Verson 1." and finally "Version 2."
135 To summarize, when the word ordering must differ, insert "1$", "2$"
136 etc. into the middle of '%s' and repeat for each instance of '%s' in
137 the phrase. If you use this "$" notation, you must use it for each
138 of the the format specifications within the string.
140 Here are a couple more examples. They are fictional but they serve to
141 illustrate how to handle special cases, should they arise:
144 #msgid "Page version '%d' named '%s' is not available."
145 #msgstr "Xyqlmn vvvm » %2$s « mnqee » %1$d « Gvbbbnbhkkk eeek."
147 The %s and %d are reversed, so '2$' and '1$' have been used to
148 indicate the new ordering. The punctuation marks for this language
149 dictate extra spacing, so this has also been accounted for in the
150 translation (i.e. the quote marks are only for emphasis, they are not
151 considered part of the %s placeholder).
154 #msgid "Page named '%s' version '%d' written by author '%s' is not available."
155 #msgstr "Qppn wwmoooppp '%3$s' vvvm '%1$s' mnqee '%2$d' Gvbbbnbhkkk eeek."
157 Name and author are reversed. Even though the position of the number
158 ('%d') isn't changed, still it must be changed to '%2$d' --- if you
159 use a '$' on one of the format specifiers you must use it on all of
160 them. The punctuation for this particular language is the same as
161 english so it is unchanged.
164 While translating the text strings if you are uncertain about the
165 syntax, look at the '.po' files of the other languages as an
166 example. If you are stuck or simply can't make any sense of all this,
167 just ask one of the PhpWiki programmers on the mailing list to help
173 Most of the work will be in the translation of the default pgsrc
174 files. As a starting point you can copy the English 'pgsrc' directory:
177 cp -rv pgsrc locale/is
179 For these 'pgsrc' files it will be sufficient to change the page names
180 to Islandic, and maybe translate the HomePage and give it an Islandic
181 name. Again, for anything you don't know, look at the 'nl' or 'de'
184 The best approach to translating the default page content is to do all
185 of your page editing in the web browser itself, then perform a page
186 dump to save the pages as MIME text files. Some of the pages are
187 locked so you will have to log into PhpWiki as the administrator
188 before you can edit them.
191 Add instructions for editing MIME headers of files before moving
192 files into '/locale/is/pgsrc'
194 - keep modification date, page name and lock, remove author.
195 Use action=PageDump - "Preview as developer format" for this.
198 Date: Sat, 4 Jul 2009 19:09:38 +0000
199 Mime-Version: 1.0 (Produced by PhpWiki 1.3.11pre)
200 Content-Type: application/x-phpwiki;
201 pagename=G%C3%A4steBuch;
205 Content-Transfer-Encoding: binary
207 - Make sure to rename files with accents in the page name converted
208 to uppercase hex codes as shown in the pagename= line of the
211 (e.g. "GästeBuch" => "G%C3%A4steBuch")
213 - Translate body text and rename plugin pages to match changes
214 specified in the '.po' file. Leave plugin code as English.
217 <<RecentChanges days||=30 show_all||=0 show_minor||=0 >>
224 The Makefile calls 'xgettext' to automatically perform a number of
225 important translation tasks:
227 * Scans through all the source code and retrieves the english
228 strings used as text arguments, then collects and indexes them into
229 the file 'phpwiki.pot'.
231 * Merges any new differences of the collected English text strings
232 with similar text strings found during any previous runs of 'make',
233 stored inside each of the translated '.po' files.
235 * Makes note of which English text strings have been added, reworded
236 or removed. The translated strings in the '.po' files are then marked
237 as "fuzzy" translations for all cases where the English text has been
238 changed. This makes it easy for translators to spot which items need
239 to be updated. (Emacs' po mode also uses this information).
241 * The necessary '.mo' files are
242 synchronized and sorted according to the translated contents of the
243 '.po' files, for each of the locale subdirectories.
245 When a new language module is added to PhpWiki, the 'Makefile' in the
246 'locale' folder also needs to be updated. The process:
248 0. Change into the locale directory (if you're not already there.)
250 1. If there isn't one already, Create a new .po (in the po/ subdirectory)
251 for your translations:
253 cp po/phpwiki.pot po/xx.po
255 where 'xx' should be the two letter character code for the language
256 you are translating to.
258 2. If you've created a new .po file (or if there are new .php source files
259 containing translatable strings,) update the Makefile:
263 3. To make sure the list of translatable strings in the .po is in sync
264 with the actual php source code:
268 4. Edit the translations in the .po file. If you have emacs available,
269 emacs' po-mode is very helpful when doing this.
271 5. Translators may include comments in the po file. If using a text
272 editor other than emacs (with po-mode), add any comments BEFORE an
273 entry, and prefix each line with # like this:
275 # This entry is important for French punctuation rules which stipulate
276 # a space before each colon.
277 #: ../lib/display.php:54 ../lib/plugin/PageGroup.php:91
278 #: ../lib/plugin/PageGroup.php:156 ../lib/plugin/PageGroup.php:167
279 #: ../lib/plugin/PageGroup.php:183 ../lib/plugin/PageGroup.php:190
280 #: ../lib/plugin/PageHistory.php:216 ../lib/plugin/UnfoldSubpages.php:164
281 #: ../themes/default/templates/head.tmpl:46
286 6. To update the compiled translation files (phpwiki.mo):
290 Make will then automatically generate and update all the necessary
291 files. If this step fails because you don't have the necessary
292 software installed, then send your '.po' files to one of the PhpWiki
293 developers who will run Makefile for you.
296 NOTE: "Fuzzy" translations will NOT be included in the final '.mo'
297 files. If you are not using the emacs editor, make sure
298 to remove the fuzzy marks from any *completed translations* before you
299 run the makefile, like this:
301 #: ../lib/plugin/BackLinks.php:44
303 msgid "These pages link to %s:"
304 msgstr "%d pages pointent vers %s."
308 #: ../lib/plugin/BackLinks.php:44
310 msgid "These pages link to %s:"
311 msgstr "%d pages pointent vers %s."
315 #: ../lib/Toolbar.php:160 ../templates/browse.html:54
318 msgstr "Bloquear página"
322 #: ../lib/Toolbar.php:160 ../templates/browse.html:54
324 msgstr "Bloquear página"
329 The template files do not need to be translated. As of PhpWiki 1.3 all
330 the text strings in the html templates are cross-referenced with the
331 translations in the '.po' files.
333 *** Note: Updating html template translations from PhpWiki 1.2 to 1.3: ***
335 The translated version of the tips for TextFormattingRules must be
336 moved from the old html template 'editpage.html', and placed into the
337 'pgsrc' for the default page of TextFormattingRules. A plugin now
338 extracts this text and inserts it when editing a page in PhpWiki,
339 rather than it being embedded within the html template itself.
341 It is suggested this paragraph would go at the top of the page. It
342 must be in a section heading entitled "Summary" in order for the
343 editpage template to find it. Of course you will substitute the
344 translations for "TextFormattingRules" and "Summary", according to the
345 wording you used for these phrases when you translated the '.po' file.
347 Refer to the English "TextFormattingRules" and German (de)
348 "TextFormatierungsRegeln" pages to see working examples.
353 After you have finished translating, you will want to see the result
354 of your efforts. Change the LANG setting in 'config.ini' to the
355 two-letter code for your language.
357 Et voilà, Phpwiki should now speak Islandic!
359 If your translation was a success, you may also want to add a
360 translation of these instructions for translating PhpWiki ;-)
364 To learn more about GNU gettext and '.po' files, you may find some
367 <http://www.iro.umontreal.ca/contrib/po/HTML/>
368 <http://www.gnu.org/directory/gettext>
371 Jan Nieuwenhuizen <janneke@gnu.org>
372 Arno Hollosi <ahollosi@mail.com>
373 Carsten Klapp <carstenklapp@users.sourceforge.net>
374 Reini Urban <rurban@x-ray.at>
376 $Id: README 7001 2009-07-06 14:23:30Z vargenau $