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' => 'phpwiki.php' 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
170 The 'phpwiki.php' files do not need to be created or edited because
171 the Makefile will create and update these files automatically. See the
172 'Makefile' section below.
177 Most of the work will be in the translation of the default pgsrc
178 files. As a starting point you can copy the English 'pgsrc' directory:
181 cp -rv pgsrc locale/is
183 For these 'pgsrc' files it will be sufficient to change the page names
184 to Islandic, and maybe translate the HomePage and give it an Islandic
185 name. Again, for anything you don't know, look at the 'nl' or 'de'
188 The best approach to translating the default page content is to do all
189 of your page editing in the web browser itself, then perform a page
190 dump to save the pages as MIME text files. Some of the pages are
191 locked so you will have to log into PhpWiki as the administrator
192 before you can edit them.
195 Add instructions for editing MIME headers of files before moving
196 files into '/locale/is/pgsrc'
198 - keep modification date, page name and lock, remove author.
199 Use action=PageDump - "Preview as developer format" for this.
202 Date: Sat, 4 Jul 2009 19:09:38 +0000
203 Mime-Version: 1.0 (Produced by PhpWiki 1.3.11pre)
204 Content-Type: application/x-phpwiki;
205 pagename=G%C3%A4steBuch;
209 Content-Transfer-Encoding: binary
211 - Make sure to rename files with accents in the page name converted
212 to uppercase hex codes as shown in the pagename= line of the
215 (e.g. "GästeBuch" => "G%C3%A4steBuch")
217 - Translate body text and rename plugin pages to match changes
218 specified in the '.po' file. Leave plugin code as English.
221 <<RecentChanges days||=30 show_all||=0 show_minor||=0 >>
228 The Makefile calls 'xgettext' to automatically perform a number of
229 important translation tasks:
231 * Scans through all the source code and retrieves the english
232 strings used as text arguments, then collects and indexes them into
233 the file 'phpwiki.pot'.
235 * Merges any new differences of the collected English text strings
236 with similar text strings found during any previous runs of 'make',
237 stored inside each of the translated '.po' files.
239 * Makes note of which English text strings have been added, reworded
240 or removed. The translated strings in the '.po' files are then marked
241 as "fuzzy" translations for all cases where the English text has been
242 changed. This makes it easy for translators to spot which items need
243 to be updated. (Emacs' po mode also uses this information).
245 * The necessary '.mo' files and 'phpwiki.php' text files are
246 synchronized and sorted according to the translated contents of the
247 '.po' files, for each of the locale subdirectories.
249 When a new language module is added to PhpWiki, the 'Makefile' in the
250 'locale' folder also needs to be updated. The process:
252 0. Change into the locale directory (if you're not already there.)
254 1. If there isn't one already, Create a new .po (in the po/ subdirectory)
255 for your translations:
257 cp po/phpwiki.pot po/xx.po
259 where 'xx' should be the two letter character code for the language
260 you are translating to.
262 2. If you've created a new .po file (or if there are new .php source files
263 containing translatable strings,) update the Makefile:
267 3. To make sure the list of translatable strings in the .po is in sync
268 with the actual php source code:
272 4. Edit the translations in the .po file. If you have emacs available,
273 emacs' po-mode is very helpful when doing this.
275 5. Translators may include comments in the po file. If using a text
276 editor other than emacs (with po-mode), add any comments BEFORE an
277 entry, and prefix each line with # like this:
279 # This entry is important for French punctuation rules which stipulate
280 # a space before each colon.
281 #: ../lib/display.php:54 ../lib/plugin/PageGroup.php:91
282 #: ../lib/plugin/PageGroup.php:156 ../lib/plugin/PageGroup.php:167
283 #: ../lib/plugin/PageGroup.php:183 ../lib/plugin/PageGroup.php:190
284 #: ../lib/plugin/PageHistory.php:216 ../lib/plugin/UnfoldSubpages.php:164
285 #: ../themes/default/templates/head.tmpl:46
290 6. To update the compiled translation files (phpwiki.mo and
295 Make will then automatically generate and update all the necessary
296 files. If this step fails because you don't have the necessary
297 software installed, then send your '.po' files to one of the PhpWiki
298 developers who will run Makefile for you.
301 NOTE: "Fuzzy" translations will NOT be included in the final '.mo' and
302 'phpwiki.php' files. If you are not using the emacs editor, make sure
303 to remove the fuzzy marks from any *completed translations* before you
304 run the makefile, like this:
306 #: ../lib/plugin/BackLinks.php:44
308 msgid "These pages link to %s:"
309 msgstr "%d pages pointent vers %s."
313 #: ../lib/plugin/BackLinks.php:44
315 msgid "These pages link to %s:"
316 msgstr "%d pages pointent vers %s."
320 #: ../lib/Toolbar.php:160 ../templates/browse.html:54
323 msgstr "Bloquear página"
327 #: ../lib/Toolbar.php:160 ../templates/browse.html:54
329 msgstr "Bloquear página"
334 The template files do not need to be translated. As of PhpWiki 1.3 all
335 the text strings in the html templates are cross-referenced with the
336 translations in the '.po' files.
338 *** Note: Updating html template translations from PhpWiki 1.2 to 1.3: ***
340 The translated version of the tips for TextFormattingRules must be
341 moved from the old html template 'editpage.html', and placed into the
342 'pgsrc' for the default page of TextFormattingRules. A plugin now
343 extracts this text and inserts it when editing a page in PhpWiki,
344 rather than it being embedded within the html template itself.
346 It is suggested this paragraph would go at the top of the page. It
347 must be in a section heading entitled "Summary" in order for the
348 editpage template to find it. Of course you will substitute the
349 translations for "TextFormattingRules" and "Summary", according to the
350 wording you used for these phrases when you translated the '.po' file.
352 Refer to the English "TextFormattingRules" and German (de)
353 "TextFormatierungsRegeln" pages to see working examples.
358 After you have finished translating, you will want to see the result
359 of your efforts. Change the LANG setting in 'config.ini' to the
360 two-letter code for your language.
362 Et voilà, Phpwiki should now speak Islandic!
364 If your translation was a success, you may also want to add a
365 translation of these instructions for translating PhpWiki ;-)
369 To learn more about GNU gettext and '.po' files, you may find some
372 <http://www.iro.umontreal.ca/contrib/po/HTML/>
373 <http://www.gnu.org/directory/gettext>
376 Jan Nieuwenhuizen <janneke@gnu.org>
377 Arno Hollosi <ahollosi@mail.com>
378 Carsten Klapp <carstenklapp@users.sourceforge.net>
379 Reini Urban <rurban@x-ray.at>
381 $Id: README 7001 2009-07-06 14:23:30Z vargenau $