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 Currently most of the language files are saved using the ISO-8859-1
100 character encoding to preserve accented characters. Make sure the text
101 editor you use is capable of performing the appropriate Latin-1
102 translation. Strictly speaking, ISO-8859-1 is *different* than Windows
103 code page 1252 or MacRoman. Upon quick inspection one will notice that
104 many of the letters do occupy the same positions in each of their'
105 respective encoding tables, so it is easy to understand how people can
106 make this false assumption.
109 PhpWiki is not able to translate between different character sets on the
110 fly (iconv). Certain languages, like Japanese or Chinese use special character
111 sets (euc-jp, utf-8), which must be defined in part four in config/config.ini.
112 Therefore other languages in different character sets will not be correctly
114 PhpWiki is not yet properly utf-8 safe. That means that certain valid utf-8 multichar
115 sequences with \0 in it, will break the traditional php string or pcre functions or
116 that the length of the string will be miscalculated.
117 There's an experimental utf-8 patch on the sf.net patches site if you want to try that.
118 See http://phpwiki.org/Utf8Migration
122 Different languages have different word ordering requirements. When a
123 key word such as a person's name needs to be added to the end of a
124 sentence in english, there is no guarantee that the same word will
125 appear at the end of a sentence once translated to another language.
127 PhpWiki has been designed with this in mind. (Standard printf
128 notations like %s and %1$s, %2$s will work with PhpWiki, even though
129 reordering of variable-substitutions is not actually part of PHP).
130 (The printf(3) manual page on your system may be of some help.)
133 Take the following English phrase as an example. This message would be
134 displayed in the browser when someone wants to compare two revisions
135 of a Wiki page. The corresponding entry for the German translation for
136 this phrase (from the file 'de.po') reads:
138 #: ../lib/diff.php:251
140 msgid "Differences between %s and %s of %s."
141 msgstr "Der Unterschiedsergebnis von %3$s, zwischen %1$s und %2$s"
143 In the English version, PhpWiki will substitute the phrases "version
144 1", "version 2" and the name of the page being compared. The
145 placeholder '%s' indicates where text will later be substituted, while
146 '%d' is used to indicate a number will be inserted.
148 Sentence structure of German is different than English, and this case
149 dictates that the "page name" must come first, then followed by
150 "Verson 1." and finally "Version 2."
152 To summarize, when the word ordering must differ, insert "1$", "2$"
153 etc. into the middle of '%s' and repeat for each instance of '%s' in
154 the phrase. If you use this "$" notation, you must use it for each
155 of the the format specifications within the string.
157 Here are a couple more examples. They are fictional but they serve to
158 illustrate how to handle special cases, should they arise:
161 #msgid "Page version '%d' named '%s' is not available."
162 #msgstr "Xyqlmn vvvm » %2$s « mnqee » %1$d « Gvbbbnbhkkk eeek."
164 The %s and %d are reversed, so '2$' and '1$' have been used to
165 indicate the new ordering. The punctuation marks for this language
166 dictate extra spacing, so this has also been accounted for in the
167 translation (i.e. the quote marks are only for emphasis, they are not
168 considered part of the %s placeholder).
171 #msgid "Page named '%s' version '%d' written by author '%s' is not available."
172 #msgstr "Qppn wwmoooppp '%3$s' vvvm '%1$s' mnqee '%2$d' Gvbbbnbhkkk eeek."
174 Name and author are reversed. Even though the position of the number
175 ('%d') isn't changed, still it must be changed to '%2$d' --- if you
176 use a '$' on one of the format specifiers you must use it on all of
177 them. The punctuation for this particular language is the same as
178 english so it is unchanged.
181 While translating the text strings if you are uncertain about the
182 syntax, look at the '.po' files of the other languages as an
183 example. If you are stuck or simply can't make any sense of all this,
184 just ask one of the PhpWiki programmers on the mailing list to help
187 The 'phpwiki.php' files do not need to be created or edited because
188 the Makefile will create and update these files automatically. See the
189 'Makefile' section below.
194 Most of the work will be in the translation of the default pgsrc
195 files. As a starting point you can copy the English 'pgsrc' directory:
198 cp -rv pgsrc locale/is
200 For these 'pgsrc' files it will be sufficient to change the page names
201 to Islandic, and maybe translate the HomePage and give it an Islandic
202 name. Again, for anything you don't know, look at the 'nl' or 'de'
205 The best approach to translating the default page content is to do all
206 of your page editing in the web browser itself, then perform a page
207 dump to save the pages as MIME text files. Some of the pages are
208 locked so you will have to log into PhpWiki as the administrator
209 before you can edit them.
212 Add instructions for editing MIME headers of files before moving
213 files into '/locale/is/pgsrc'
215 - keep modification date, page name and lock, remove author.
216 Use action=PageDump - "Preview as developer format" for this.
219 Date: Sun, 27 Jan 2002 17:28:55 -0500
220 Mime-Version: 1.0 (Produced by PhpWiki 1.3.2-jeffs-hacks)
221 X-Rcs-Id: $Id: README,v 1.13 2005-01-08 22:41:42 rurban Exp $
222 Content-Type: application/x-phpwiki;
223 pagename=Neueste%C4nderungen;
226 Content-Transfer-Encoding: binary
228 - Make sure to rename files with accents in the page name converted
229 to uppercase hex codes as shown in the pagename= line of the
232 (e.g. "GästeBuch" => "G%E4steBuch")
234 - Translate body text and rename plugin pages to match changes
235 specified in the '.po' file. Leave plugin code as english.
238 <?plugin RecentChanges days||=30 show_all||=0 show_minor||=0 ?>
245 The Makefile calls 'xgettext' to automatically perform a number of
246 important translation tasks:
248 * Scans through all the source code and retrieves the english
249 strings used as text arguments, then collects and indexes them into
250 the file 'phpwiki.pot'.
252 * Merges any new differences of the collected English text strings
253 with similar text strings found during any previous runs of 'make',
254 stored inside each of the translated '.po' files.
256 * Makes note of which English text strings have been added, reworded
257 or removed. The translated strings in the '.po' files are then marked
258 as "fuzzy" translations for all cases where the English text has been
259 changed. This makes it easy for translators to spot which items need
260 to be updated. (Emacs' po mode also uses this information).
262 * The necessary '.mo' files and 'phpwiki.php' text files are
263 synchronized and sorted according to the translated contents of the
264 '.po' files, for each of the locale subdirectories.
266 When a new language module is added to PhpWiki, the 'Makefile' in the
267 'locale' folder also needs to be updated. The process:
269 0. Change into the locale directory (if you're not already there.)
271 1. If there isn't one already, Create a new .po (in the po/ subdirectory)
272 for your translations:
274 cp po/phpwiki.pot po/xx.po
276 where 'xx' should be the two letter character code for the language
277 you are translating to.
279 2. If you've created a new .po file (or if there are new .php source files
280 containing translatable strings,) update the Makefile:
284 3. To make sure the list of translatable strings in the .po is in sync
285 with the actual php source code:
289 4. Edit the translations in the .po file. If you have emacs available,
290 emacs' po-mode is very helpful when doing this.
292 5. Translators may include comments in the po file. If using a text
293 editor other than emacs (with po-mode), add any comments BEFORE an
294 entry, and prefix each line with # like this:
296 # This entry is important for French punctuation rules which stipulate
297 # a space before each colon.
298 #: ../lib/display.php:54 ../lib/plugin/PageGroup.php:91
299 #: ../lib/plugin/PageGroup.php:156 ../lib/plugin/PageGroup.php:167
300 #: ../lib/plugin/PageGroup.php:183 ../lib/plugin/PageGroup.php:190
301 #: ../lib/plugin/PageHistory.php:216 ../lib/plugin/UnfoldSubpages.php:164
302 #: ../themes/default/templates/head.tmpl:46
307 6. To update the compiled translation files (phpwiki.mo and
312 Make will then automatically generate and update all the necessary
313 files. If this step fails because you don't have the necessary
314 software installed, then send your '.po' files to one of the PhpWiki
315 developers who will run Makefile for you.
318 NOTE: "Fuzzy" translations will NOT be included in the final '.mo' and
319 'phpwiki.php' files. If you are not using the emacs editor, make sure
320 to remove the fuzzy marks from any *completed translations* before you
321 run the makefile, like this:
323 #: ../lib/plugin/BackLinks.php:44
325 msgid "These pages link to %s:"
326 msgstr "%d pages pointent vers %s."
330 #: ../lib/plugin/BackLinks.php:44
332 msgid "These pages link to %s:"
333 msgstr "%d pages pointent vers %s."
337 #: ../lib/Toolbar.php:160 ../templates/browse.html:54
340 msgstr "Bloquear página"
344 #: ../lib/Toolbar.php:160 ../templates/browse.html:54
346 msgstr "Bloquear página"
351 The template files do not need to be translated. As of PhpWiki 1.3 all
352 the text strings in the html templates are cross-referenced with the
353 translations in the '.po' files.
355 *** Note: Updating html template translations from PhpWiki 1.2 to 1.3: ***
357 The translated version of the tips for TextFormattingRules must be
358 moved from the old html template 'editpage.html', and placed into the
359 'pgsrc' for the default page of TextFormattingRules. A plugin now
360 extracts this text and inserts it when editing a page in PhpWiki,
361 rather than it being embedded within the html template itself.
363 It is suggested this paragraph would go at the top of the page. It
364 must be in a section heading entitled "Summary" in order for the
365 editpage template to find it. Of course you will substitute the
366 translations for "TextFormattingRules" and "Summary", according to the
367 wording you used for these phrases when you translated the '.po' file.
369 Refer to the English "TextFormattingRules" and German (de)
370 "TextFormatierungsRegeln" pages to see working examples.
375 After you have finished translating, you will want to see the result
376 of your efforts. Change the LANG setting in 'config.ini' to the
377 two-letter code for your language.
379 Et voilà, Phpwiki should now speak Islandic!
381 If your translation was a success, you may also want to add a
382 translation of these instructions for translating PhpWiki ;-)
386 To learn more about GNU gettext and '.po' files, you may find some
389 <http://www.iro.umontreal.ca/contrib/po/HTML/>
390 <http://www.gnu.org/directory/gettext>
393 Jan Nieuwenhuizen <janneke@gnu.org>
394 Arno Hollosi <ahollosi@mail.com>
395 Carsten Klapp <carstenklapp@users.sourceforge.net>
396 Reini Urban <rurban@x-ray.at>
398 $Id: README,v 1.13 2005-01-08 22:41:42 rurban Exp $