phpwiki-checkins

[Carsten K. <car...@us...>]

Update of /cvsroot/phpwiki/phpwiki/locale
In directory usw-pr-cvs1:/tmp/cvs-serv21563/phpwiki/locale

Modified Files:
	README 
Log Message:
Added a new section on formal vs. informal language translation (feedback please).
Explained how to specify reordering of variable substitution (Some real-world examples would be a nice addition to this).
Minor reformatting and typo fixes.

Index: README
===================================================================
RCS file: /cvsroot/phpwiki/phpwiki/locale/README,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -r1.3 -r1.4
*** README	2001/12/27 04:25:02	1.3
--- README	2001/12/27 07:33:23	1.4
***************
*** 1,8 ****
  
- Phpwiki uses GNU gettext tools to provide and maintain multi-lingual
- messages for different languages.
- 
-     <http://www.gnu.org/directory/gettext>
- 
  This document describes how to add a new language translation to PhpWiki.
  
--- 1,3 ----
***************
*** 12,25 ****
  one of the supported languages, like this:
  
!    //  Select your language - default language "C": English
!    // other languages available: Dutch "nl", Spanish "es", German "de"
!    // $LANG="C";
!    $LANG="is";
  
  
  General Steps
  =============
! The general steps to creating a new language module for PhpWiki are as
! follows:
  
  1. Copy and rename the master template to create a new file for your
--- 7,57 ----
  one of the supported languages, like this:
  
!     // Select your language/locale - default language "C": English
!     // other languages available: Dutch "nl", Spanish "es", German "de",
!     // Swedish "sv", and Italian, "it".
!     // $LANG="C";
!     $LANG="it";
! 
! 
! Phpwiki uses GNU gettext tools to provide and maintain multi-lingual
! messages for different languages. Even if you are already familiar
! with xgettext you will want to read this document to be aware of
! translation issues and tips specific to PhpWiki; perhaps skimming
! through the Makefile section.
! 
! PhpWiki does not require gettext support to be compiled in to PHP.  It
! automatically provides a pure PHP replacement in case it's not available.
! 
! 
! Formalities
! ===========
! The modern English language has no clear rules for differentiating
! between the formal and informal use of the spoken word. This both
! simplifies and complicates matters for translators, as many languages
! do still make such a distinction. For the most part, PhpWiki is written
! using the casual forms of messages and explanatory text--after all the
! WikiWikiWeb is an open and friendly place. :-)
! 
! However, there is no reason why translations of Wiki commands like
! "Edit" or "FindPages" should not be written formally. For the sake of
! recognition or clarity when the word function is the same as another
! common computer term or menu-item, if you feel it would be more
! effective to employ a formal variation then please do so. When the
! formal word is significantly longer than the informal word, make a
! judgement call or substitute an abbreviation, provided that it will
! be easily recognised.
! 
! Remember that a good and thorough translation is a subjective and
! collective process. Once people have had a chance to test-drive your
! newly-translated PhpWiki there will always be suggestions for
! reshaping and improving it.
  
+ Diversity and Change are part of WikiEssence. By all means don't
+ belabour the translation process, and have some fun!
  
+ 
  General Steps
  =============
! The general steps to creating a new language module for PhpWiki:
  
  1. Copy and rename the master template to create a new file for your
***************
*** 28,32 ****
  2. Translate all the strings in the new language file ('.po file').
  
! 3. Run "Make" to automatically create or update any additional files
     ('.po' => '.mo' => 'phpwiki.php' files).
  
--- 60,64 ----
  2. Translate all the strings in the new language file ('.po file').
  
! 3. Run 'make' to automatically create or update any additional files
     ('.po' => '.mo' => 'phpwiki.php' files).
  
***************
*** 46,73 ****
  'is.po' ('is' is the code for Islandic). Next, translate all the
  strings inside 'is.po' from English to Islandic. Unix Hint: Emacs has
! a handy "po translation mode" for you.
! 
! Important: Currently all the language files are saved using the
! ISO-8859-1 character encoding to preserve accented characters. Make
! sure the text editor you use is capable of the appropriate Latin-1
! translation. Strictly speaking, ISO-8859-1 is *different* than Windows
! code page 1252 or MacRoman. Upon quick inspection one will notice that
! many of the letters do occupy the same positions in each of their'
! respective encoding tables, so it is easy to understand how people
! have made such a false assumption.
! 
! <FIXME> Add a note about %s and variable reordering: %3$s, %1$s, %2$s. </FIXME>
  
! Example of word-substitution-reordering from 'de.po':
      #: ../lib/diff.php:251
      #, c-format
      msgid "Differences between %s and %s of %s."
!     msgstr "Der Unterschiedsergebnis von %3$s, zwischen %1$s und %2$s."
  
  While translating the text strings if you are uncertain about the
  syntax, look at the '.po' files of the other languages as an
! example. The 'phpwiki.php' file does not need to be created or edited
! because the Makefile will create and update these files automatically
! (see below**).
  
  
--- 78,159 ----
  'is.po' ('is' is the code for Islandic). Next, translate all the
  strings inside 'is.po' from English to Islandic. Unix Hint: Emacs has
! a handy "po translation mode" for you. See README.coding in the doc folder.
  
! Important note about character encoding: 
!   Currently all the language files are saved using the ISO-8859-1
!   character encoding to preserve accented characters. Make sure the text
!   editor you use is capable of performing the appropriate Latin-1
!   translation. Strictly speaking, ISO-8859-1 is *different* than Windows
!   code page 1252 or MacRoman. Upon quick inspection one will notice that
!   many of the letters do occupy the same positions in each of their'
!   respective encoding tables, so it is easy to understand how people can
!   make this false assumption.
! 
! 
! Word Reordering
! ---------------
! Different languages have different word ordering requirements. When a
! key word such as a person's name needs to be added to the end of a
! sentence in english, there is no guarantee that the same word will
! appear at the end of a sentence once translated to another language.
! 
! PhpWiki has been designed with this in mind. (Standard gettext
! notations like %s and %1$s, %2$s will work with PhpWiki, even though
! reordering of variable-substitutions is not actually part of PHP).
! 
! Take the following English phrase as an example. This message would be
! displayed in the browser when someone wants to compare two revisions
! of a Wiki page. The corresponding entry for the German translation for
! this phrase (from the file 'de.po') reads:
!  
      #: ../lib/diff.php:251
      #, c-format
      msgid "Differences between %s and %s of %s."
!     msgstr "Der Unterschiedsergebnis von %3$s, zwischen %1$s und %2$s"
! 
! In the English version, PhpWiki will substitute the phrases "version
! 1", "version 2" and the name of the page being compared. The
! placeholder '%s' indicates where text will later be substituted, while
! '%d' is used to indicate a number will be inserted.
! 
! Sentence structure of German is different than English, and this case
! dictates that the "page name" must come first, then followed by
! "Verson 1." and finally "Version 2."
  
+ To summarize, when the word ordering must differ, insert "1$", "2$"
+ etc. into the middle of '%s' and repeat for each instance of '%s' in
+ the phrase.
+ 
+ Here are a couple more examples. They are fictional but they serve to
+ illustrate how to handle special cases, should they arise:
+ 
+ 
+ #msgid "Page version '%d' named '%s' is not available."
+ #msgstr "Xyqlmn vvvm » %s « mnqee » %d « Gvbbbnbhkkk eeek."
+ 
+ Even though %s and %d are reversed, no '1$' and '2$ are needed because
+ one is a text string and the other is a number. The punctuation marks
+ for this language dictate extra spacing, so this has also been accounted
+ for in the translation (i.e. the quote marks are only for emphasis, they
+ are not considered part of the %s placeholder).
+ 
+ 
+ #msgid "Page named '%s' version '%d' written by author '%s' is not available."
+ #msgstr "Qppn wwmoooppp '%2$s' vvvm '%1$s' mnqee '%d' Gvbbbnbhkkk eeek."
+ 
+ Name and author are reversed. No special treatment is needed for the
+ number, because it is the only one present. The punctuation for this
+ particular language is the same as english so it is unchanged.
+ 
+ 
  While translating the text strings if you are uncertain about the
  syntax, look at the '.po' files of the other languages as an
! example. If you are stuck or simply can't make any sense of all this,
! just ask one of the PhpWiki programmers on the mailing list to help
! out.
! 
! The 'phpwiki.php' files do not need to be created or edited because
! the Makefile will create and update these files automatically. See the
! 'Makefile' section below.
  
  
***************
*** 82,93 ****
  For these 'pgsrc' files it will be sufficient to change the page names
  to Islandic, and maybe translate the HomePage and give it an Islandic
! name. Again, for anything you don't know, look at the `nl' or `de'
  versions.
  
! The best approach to translating the default pages is to do all of
! your page editing in the web browser itself, then perform a page dump
! to save the pages as MIME text files.  Some of the pages are locked so
! you will have to log into PhpWiki as the administrator before you can
! edit them.
  
  <FIXME>
--- 168,179 ----
  For these 'pgsrc' files it will be sufficient to change the page names
  to Islandic, and maybe translate the HomePage and give it an Islandic
! name. Again, for anything you don't know, look at the 'nl' or 'de'
  versions.
  
! The best approach to translating the default page content is to do all
! of your page editing in the web browser itself, then perform a page
! dump to save the pages as MIME text files.  Some of the pages are
! locked so you will have to log into PhpWiki as the administrator
! before you can edit them.
  
  <FIXME>
***************
*** 95,99 ****
     files into '/locale/is/pgsrc'
  
!  - keep modification date, page name and lock, remove author).
     Example:
      Content-Type: application/x-phpwiki;
--- 181,185 ----
     files into '/locale/is/pgsrc'
  
!  - keep modification date, page name and lock, remove author.
     Example:
      Content-Type: application/x-phpwiki;
***************
*** 115,123 ****
  
  Makefile
! --------
! The Makefile automatically performs a number of important translation tasks:
! 
!  * Retrieves all the English text strings used throughout the php
!    code, then collects and indexes them into the file 'phpwiki.pot'.
  
   * Merges any new differences of the collected English text strings
--- 201,211 ----
  
  Makefile
! -------- 
! The Makefile calls 'xgettext' to automatically perform a number of
! important translation tasks:
! 
!  * Scans through all the source code and retrieves the english
!    strings used as text arguments, then collects and indexes them into
!    the file 'phpwiki.pot'.
  
   * Merges any new differences of the collected English text strings
***************
*** 135,141 ****
     '.po' files, for each of the locale subdirectories.
  
! When a new language module is added to PhpWiki the 'Makefile' in the
  'locale' folder also needs to be updated. Add the two-letter gettext
! language code to the list of all languages known by PhpWiki, by
  changing the variable ALL_LINGUAS. In this example 'is' was added for
  Icelandic:
--- 223,229 ----
     '.po' files, for each of the locale subdirectories.
  
! When a new language module is added to PhpWiki, the 'Makefile' in the
  'locale' folder also needs to be updated. Add the two-letter gettext
! language code to the list of all languages known to PhpWiki, by
  changing the variable ALL_LINGUAS. In this example 'is' was added for
  Icelandic:
***************
*** 158,177 ****
  --------------
  The template files do not need to be translated. As of PhpWiki 1.3 all
! the text strings have been moved out of the html templates into the
! '.po' files.
  
  *** Note: Updating html template translations from PhpWiki 1.2 to 1.3: ***
  
!     The translated version of the tips for TextFormattingRules
!     must be moved from the old html template 'editpage.html', and placed
!     into the 'pgsrc' for the default page of TextFormattingRules. A plugin
!     now extracts this text and inserts it when editing a page in PhpWiki,
!     rather than putting it into the html template itself.
! 
! It is suggested to put the paragraph at the top of the page. It must
! be in a section heading entitled "Summary". Of course you will
! substitute the translations for "TextFormattingRules" and "Summary",
! according to the wording you used for these phrases when you
! translated the '.po' file.
  
  Refer to the English "TextFormattingRules" and German (de)
--- 246,265 ----
  --------------
  The template files do not need to be translated. As of PhpWiki 1.3 all
! the text strings in the html templates are cross-referenced with the
! translations in the '.po' files.
  
  *** Note: Updating html template translations from PhpWiki 1.2 to 1.3: ***
  
! The translated version of the tips for TextFormattingRules must be
! moved from the old html template 'editpage.html', and placed into the
! 'pgsrc' for the default page of TextFormattingRules. A plugin now
! extracts this text and inserts it when editing a page in PhpWiki,
! rather than it being embedded within the html template itself.
! 
! It is suggested this paragraph would go at the top of the page. It
! must be in a section heading entitled "Summary" in order for the
! editpage template to find it. Of course you will substitute the
! translations for "TextFormattingRules" and "Summary", according to the
! wording you used for these phrases when you translated the '.po' file.
  
  Refer to the English "TextFormattingRules" and German (de)
***************
*** 181,185 ****
  Finale
  ======
! After you have finished translating, you may want to check the result
  of your efforts. Change the $LANG setting in 'index.php' to the
  two-letter code for your language.
--- 269,273 ----
  Finale
  ======
! After you have finished translating, you will want to see the result
  of your efforts. Change the $LANG setting in 'index.php' to the
  two-letter code for your language.
***************
*** 188,192 ****
  
  If your translation was a success, you may also want to add a
! translation of these instructions for PhpWiki ;-)
  
  About gettext
--- 276,280 ----
  
  If your translation was a success, you may also want to add a
! translation of these instructions for translating PhpWiki ;-)
  
  About gettext