Documentation update.

git-svn-id: svn://pmwiki.org/pmwiki/trunk@2577 524c5546-5005-0410-9a3e-e25e191bd360

1 files changed, 8 insertions, 8 deletions

diff --git a/wikilib.d/PmWiki.Internationalizations b/wikilib.d/PmWiki.Internationalizations
index dc27ec72..70b48fb9 100644
--- a/wikilib.d/PmWiki.Internationalizations
+++ b/wikilib.d/PmWiki.Internationalizations
@@ -1,11 +1,11 @@
-version=pmwiki-2.2.15 ordered=1 urlencoded=1
-agent=Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 5.1; Trident/4.0; GTB6.4; .NET CLR 1.0.3705; .NET CLR 1.1.4322; .NET CLR 2.0.50727; OfficeLiveConnector.1.3; OfficeLivePatch.0.0; .NET CLR 3.0.4506.2152; .NET CLR 3.5.30729)
-author=SchreyP
+version=pmwiki-2.2.17 ordered=1 urlencoded=1
+agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-GB; rv:1.9.2.8) Gecko/20100722 Firefox/3.6.8 FirePHP/0.4
+author=FrankS
 charset=ISO-8859-1
-csum=typo
-host=81.243.198.233
+csum=
+host=84.86.229.36
 name=PmWiki.Internationalizations
-rev=96
+rev=99
 targets=Group.Name,Group.XLPage,Group.XLPageLocal,PmWiki.OtherLanguages,PmWiki.UTF-8,PmWikiFr.XLPage,PmWiki.WikiGroup,PmWiki.GroupCustomizations,Cookbook.MultiLanguage,PmWiki.PmWiki
-text=(:Summary: Language internationalisation of web pages:)%0a[[#include]]%0aPmWiki supports internationalization (internationalisation) of web pages, allowing accented characters to appear in page names and almost complete customization of PmWiki's prompts.  %0a[[#includeend]]%0aMost customization is provided via the XLPage() function in PmWiki, which loads a set of translation variables from a wiki page (typically named XLPage, but it can be named anything you wish).%0a%0aThe rest of this page is devoted to the installation, configuration and usage of other language(s) support. If you are looking for tools and help to ''localize'' PmWiki in your language, or how you can improve the existing translations, start on pmwiki.org with the page [[(http://www.pmwiki.org/wiki/Localization/)Localization]] - The translation Portal.%0a%0a>>rframe font-size:smaller clear:right%3c%3c%0a(:pagelist fmt=#languagelist name=PmWiki* list=normal order=$:Language $:Language=- :)%0a(:if false:)%0a[[#languagelist]]%0a(:template each:)%0a-%3c [[{=$Group}/{=$Name}]] {=$:Language} ~ [-[[{=$Group}/XLPage]]-] (:if exists {=$Group}.XLPageLocal:) [-[[{=$Group}/XLPageLocal]]-] (:ifend:)%0a[[#languagelistend]]%0a(:ifend:)%0a>>%3c%3c%0a!! Loading Translation Pages%0a%0aPages for many [[(PmWiki:)other languages]] have already been created and maintained at the pmichaud.com site.  You can download an archive of these translations from http://www.pmwiki.org/pub/pmwiki/i18n/ .  Simply download the appropriate language archive(s), and unpack the archive(s) into the directory containing your ''pmwiki.php'' installation.  Each archive contains a number of page files that are placed in your ''wikilib.d/'' directory, and some special scripts for translations that use a character set other than iso-8859-1 (PmWiki's default). You can also use [[UTF-8]] charset.%0a%0aOnce the translation pages are installed, you enable a language by adding a call to `XLPage() in your ''config.php'' file.  For example, to select French language prompts, one would specify%0a%0a->[@XLPage('fr','PmWikiFr.XLPage');@]%0a%0awhich says to load the translations for French ('fr') from the page [[PmWikiFr.XLPage]].  It's perfectly okay to load multiple pages; so if you want to create your own local translations without changing the ones you got from an i18n archive, just create another page (see below) and load it on top. Be sure that you load first the page with your local changes:%0a%0a-> [@%0aXLPage('fr','PmWikiFr.XLPageLocal');  # my local translations%0aXLPage('fr','PmWikiFr.XLPage');       # from i18n.tgz%0a@]%0a%0aIf your intention is to offer multiple languages on your site, and use [[Wiki Group]]s as language selectors, you may want to place this code in local customizations files (see [[Group Customizations]]). For example, if your site is published in French and English, and the French pages are in a group called Fr, you could create a file named Fr.php in the ''local/'' directory which contains:%0a%0a-> [@%0a%3c?php if (!defined('PmWiki')) exit();%0a##change to French language%0aXLPage('fr','PmWikiFr.XLPage');%0a@]%0a%0aYou may wish to create a page called ''PmwikiFr.php'' with the same content to access the French documentation in the PmwikiFr group.  ''En.php'' is not necessary in this case since English is the default language.%0a%0aAn alternative to the above would be to add to ''config.php'' the following, which tests if there is an XLPage in a group, and if it finds one it gets loaded:%0a%0a-> [@    %0a$xlpage = FmtPageName('$Group.XLPage', $pagename);%0aif (PageExists($xlpage)) XLPage($xlpage, $xlpage);%0a@]%0a%0aWith this method you would need to copy any relevant XLPage into any group which needs the different language support.%0a%0aSee also [[Cookbook:MultiLanguage]] {Cookbook/MultiLanguage$:Summary}%0a%0a!![[#CreatingNewTranslations]]Creating New Translations%0a%0aIf language pages don't exist for your desired language, it's easy to create one!  An XLPage translation file simply contains lines of the form%0a%0a->[@'phrase' => 'translated phrase',@]%0a%0awhere "phrase" is an internationalized phrase (denoted by [@$[phrase]@]) in PmWiki's $...Fmt variables, and "translated phrase" is what should be printed in your particular language.  For example, the line (in [@PmWikiFr.XLPage@])%0a%0a->[@'Search' => 'Rechercher',@]%0a%0aconverts "[@$[Search]@]" to "Rechercher" on output.  The file [[http://www.pmwiki.org/wiki/Localization/XLPageTemplate|Localization:XLPageTemplate]] is a good starting point for creating a new XLPage and has most of PmWiki's key phrases already listed in it.  %0a%0aIf you create new versions of PmWiki pages in other languages, please consider adding them to the [[PmWiki:PmWiki | main PmWiki site]] so that they can be made available to others in the i18n archives!%0a%0a->%25note%25 The term "i18n" is commonly used as an abbreviation for the English word "internationalization".  The abbreviation is derived from the fact that there are 18 letters between the "i" and the final "n" and few people want to type them all out.%0a%0a!! Enabling "Special" Characters in WikiLinks%0a%0aTo enable "special" characters like for example German umlauts in WikiLinks, it is necessary to configure the server locale to ensure that PmWiki uses the proper character set definition.%0a%0aIf this is not possible due to limited access to the server configuration, PmWiki can be configured to use a specific locale by using the XLPage options (see [[(http://www.pmwiki.org/wiki/Localization/)XLPageTemplate]]).%0a%0aFor German umlauts, you'd need for example:%0a%0a*[='Locale' => 'deu',=] %3c- for Windows servers, see [[http://msdn.microsoft.com/en-us/library/39cwe7zf.aspx|MSDN List of locale identifiers]]%0a*[='Locale' => 'de_DE',=] %3c- for Linux servers%0a%0aNote that the locale identifier depends on the operation system and perhaps on the specific installation.%0a%0a[[#notes]]%0a!! Notes%0a%0a%0a%0a>>faq%3c%3c [[#faq]]%0a%0aQ: If my wiki is internationalized by ''config.php'', how do I revert a specific group to English?%0a%0aA: Use [@$XLLangs = array('en');@] in the group's [[ group customization(s)]] file.%0a%0aQ: If my wiki is in English and I want just one page, or group, in Spanish do I say [@XLPage('es','PmWikiEs.XLPage');@] in the group or page configuration file?%0a%0aA: Yes, that is usually the best method. If you were doing this with many scattered pages, or with several languages, you might find it easier to maintain if you load the translations all in config.php like this:%0a%0a   XLPage('es','PmWikiEs.XLPage');%0a   XLPage('fr','PmWikiFr.XLPage');%0a   XLPage('ru','PmWikiRu.XLPage');%0a   $XLLangs = array('en');%0a%0aA: Then in each group or page configuration file, you'd just use $XLLangs = array('es'); to set the language to use (in this case, Spanish). Note that though this method is easier to maintain, its somewhat slower because it loads all the dictionaries for each page view, even if they won't be used.%0a%0aQ: What does the first parameter of this function stand for? How can it be used?%0a%0aA: The XLPage mechanism allows multiple sets of translations to be loaded,%0aand the first parameter is used to distinguish them.  %0a%0aFor example, suppose I want to have translations for both normal French%0aand "Canadian" French.  Rather than maintain two entirely separate sets%0aof pages, I could do:%0a%0a    XLPage('fr', 'PmWikiFr.XLPage');%0a    XLPage('fr-ca', 'PmWikiFrCa.XLPage');%0a%0aPmWikiFr.XLPage would contain all of the standard French translations,%0awhile PmWikiFrCA.XLPage would only need to contain "Canada-specific"%0atranslations -- i.e., those that are different from the ones in the%0aFrench page.%0a%0aThe first parameter distinguishes the two sets of translations.%0aIn addition, a ''config.php'' script can use the $XLLangs variable%0ato adjust the order of translation, so if there was a group or%0apage where I only wanted the standard French translation, I%0acan set%0a%0a    $XLLangs = array('fr', 'en');%0a%0aand PmWiki will use only the 'fr' and 'en' translations (in that order),%0ano matter how many translations have been loaded with XLPage().%0a
-time=1270475012
+text=(:Summary: Language internationalisation of web pages:)%0a[[#include]]%0aPmWiki supports internationalization (internationalisation) of web pages, allowing accented characters to appear in page names and almost complete customization of PmWiki's prompts.  %0a[[#includeend]]%0aMost customization is provided via the XLPage() function in PmWiki, which loads a set of translation variables from a wiki page (typically named XLPage, but it can be named anything you wish).%0a%0aThe rest of this page is devoted to the installation, configuration and usage of other language(s) support. If you are looking for tools and help to ''localize'' PmWiki in your language, or how you can improve the existing translations, start on pmwiki.org with the page [[(http://www.pmwiki.org/wiki/Localization/)Localization]] - The translation Portal.%0a%0a>>rframe font-size:smaller clear:right%3c%3c%0a(:pagelist fmt=#languagelist name=PmWiki* list=normal order=$:Language $:Language=- :)%0a(:if false:)%0a[[#languagelist]]%0a(:template each:)%0a-%3c [[{=$Group}/{=$Name}]] {=$:Language} ~ [-[[{=$Group}/XLPage]]-] (:if exists {=$Group}.XLPageLocal:) [-[[{=$Group}/XLPageLocal]]-] (:ifend:)%0a[[#languagelistend]]%0a(:ifend:)%0a>>%3c%3c%0a!! Loading Translation Pages%0a%0aPages for many [[(PmWiki:)other languages]] have already been created and maintained at the pmichaud.com site.  You can download an archive of these translations from http://www.pmwiki.org/pub/pmwiki/i18n/ .  Simply download the appropriate language archive(s), and unpack the archive(s) into the directory containing your ''pmwiki.php'' installation.  Each archive contains a number of page files that are placed in your ''wikilib.d/'' directory, and some special scripts for translations that use a character set other than iso-8859-1 (PmWiki's default). You can also use [[UTF-8]] charset.%0a%0aOnce the translation pages are installed, you enable a language by adding a call to `XLPage() in your ''config.php'' file.  For example, to select French language prompts, one would specify%0a%0a->[@XLPage('fr','PmWikiFr.XLPage');@]%0a%0awhich says to load the translations for French ('fr') from the page [[PmWikiFr.XLPage]].  It's perfectly okay to load multiple pages; so if you want to create your own local translations without changing the ones you got from an i18n archive, just create another page (see below) and load it on top. Be sure that you load first the page with your local changes:%0a%0a-> [@%0aXLPage('fr','PmWikiFr.XLPageLocal');  # my local translations%0aXLPage('fr','PmWikiFr.XLPage');       # from i18n.tgz%0a@]%0a%0aIf your intention is to offer multiple languages on your site, and use [[Wiki Group]]s as language selectors, you may want to place this code in local customizations files (see [[Group Customizations]]). For example, if your site is published in French and English, and the French pages are in a group called Fr, you could create a file named Fr.php in the ''local/'' directory which contains:%0a%0a-> [@%0a%3c?php if (!defined('PmWiki')) exit();%0a##change to French language%0aXLPage('fr','PmWikiFr.XLPage');%0a@]%0a%0aYou may wish to create a page called ''PmwikiFr.php'' with the same content to access the French documentation in the PmwikiFr group.  ''En.php'' is not necessary in this case since English is the default language.%0a%0aAn alternative to the above would be to add to ''config.php'' the following, which tests if there is an XLPage in a group, and if it finds one it gets loaded:%0a%0a-> [@    %0a$xlpage = FmtPageName('$Group.XLPage', $pagename);%0aif (PageExists($xlpage)) XLPage($xlpage, $xlpage);%0a@]%0a%0aWith this method you would need to copy any relevant XLPage into any group which needs the different language support.%0a%0aSee also [[Cookbook:MultiLanguage]] {Cookbook/MultiLanguage$:Summary}%0a%0a!![[#CreatingNewTranslations]]Creating New Translations%0a%0aIf language pages don't exist for your desired language, it's easy to create one!  An XLPage translation file simply contains lines of the form%0a%0a->[@'phrase' => 'translated phrase',@]%0a%0awhere "phrase" is an internationalized phrase (denoted by [@$[phrase]@]) in PmWiki's $...Fmt variables, and "translated phrase" is what should be printed in your particular language.  For example, the line (in [@PmWikiFr.XLPage@])%0a%0a->[@'Search' => 'Rechercher',@]%0a%0aconverts "[@$[Search]@]" to "Rechercher" on output.  The file [[http://www.pmwiki.org/wiki/Localization/XLPageTemplate|Localization:XLPageTemplate]] is a good starting point for creating a new XLPage and has most of PmWiki's key phrases already listed in it.  %0a%0aIf you create new versions of PmWiki pages in other languages, please consider adding them to the [[PmWiki:PmWiki | main PmWiki site]] so that they can be made available to others in the i18n archives!%0a%0a->%25note%25 The term "i18n" is commonly used as an abbreviation for the English word "internationalization".  The abbreviation is derived from the fact that there are 18 letters between the "i" and the final "n" and few people want to type them all out.%0a%0a!! Enabling "Special" Characters in WikiLinks%0a%0aTo enable "special" characters like for example German umlauts in WikiLinks, it is necessary to configure the server locale to ensure that PmWiki uses the proper character set definition.%0a%0aIf this is not possible due to limited access to the server configuration, PmWiki can be configured to use a specific locale by using the XLPage options (see [[(http://www.pmwiki.org/wiki/Localization/)XLPageTemplate]]).%0a%0aFor German umlauts, you'd need for example:%0a%0a*[='Locale' => 'deu',=] %3c- for Windows servers, see [[http://msdn.microsoft.com/en-us/library/39cwe7zf.aspx|MSDN List of locale identifiers]]%0a*[='Locale' => 'de_DE',=] %3c- for Linux servers%0a%0aNote that the locale identifier depends on the operation system and perhaps on the specific installation.%0a%0a[[#notes]]%0a!! Notes%0a%0a%0a%0a>>faq%3c%3c [[#faq]]%0a%0aQ: If my wiki is internationalized by ''config.php'', how do I revert a specific group to English?%0a%0aA: Use [@$XLLangs = array('en');@] in the group's [[ group customization(s)]] file.%0a%0aQ: If my wiki is in English and I want just one page, or group, in Spanish do I say [@XLPage('es','PmWikiEs.XLPage');@] in the group or page configuration file?%0a%0aA: Yes, that is usually the best method. If you were doing this with many scattered pages, or with several languages, you might find it easier to maintain if you load the translations all in config.php like this:%0a%0a   XLPage('es','PmWikiEs.XLPage');%0a   XLPage('fr','PmWikiFr.XLPage');%0a   XLPage('ru','PmWikiRu.XLPage');%0a   $XLLangs = array('en');%0a%0aA: Then in each group or page configuration file, you'd just use $XLLangs = array('es'); to set the language to use (in this case, Spanish). Note that though this method is easier to maintain, its somewhat slower because it loads all the dictionaries for each page view, even if they won't be used.%0a%0aQ: What does the first parameter of this function stand for? How can it be used?%0a%0aA: The XLPage mechanism allows multiple sets of translations to be loaded,%0aand the first parameter is used to distinguish them.  %0a%0aFor example, suppose I want to have translations for both normal French%0aand "Canadian" French.  Rather than maintain two entirely separate sets%0aof pages, I could do:%0a%0a    XLPage('fr', 'PmWikiFr.XLPage');%0a    XLPage('fr-ca', 'PmWikiFrCa.XLPage');%0a%0aPmWikiFr.XLPage would contain all of the standard French translations,%0awhile PmWikiFrCA.XLPage would only need to contain "Canada-specific"%0atranslations -- i.e., those that are different from the ones in the%0aFrench page.%0a%0aThe first parameter distinguishes the two sets of translations.%0aIn addition, a ''config.php'' script can use the $XLLangs variable%0ato adjust the order of translation, so if there was a group or%0apage where I only wanted the standard French translation, I%0acan set%0a%0a    $XLLangs = array('fr', 'en');%0a%0aand PmWiki will use only the 'fr' and 'en' translations (in that order),%0ano matter how many translations have been loaded with XLPage().%0a%0aQ: How can I use PHP to add a translation for an individual string on the fly?%0a%0aA: Use the XLSDV() function to provide a translation for a specific (English) string. For instance, with this in config.php%0a%0a    XLSDV('nl', array('my English expression'=>'mijn Nederlandse uitdrukking'));%0a%0aany instance of the variable expression [@$[my English expression]@] in wiki mark-up will be displayed as ''my English expression'' in default (English) context, but as ''mijn Nederlandse uitdrukking'' in Dutch (nl) context, i.e. when [@XLPage('nl',...)@] has been called for that page in config.php or a cookbook recipe.%0a%0aBut beware: XLPage() uses XLSDV() internally for its translation pairs, too, and only the first definition is accepted! Thus, if the Dutch XLPage already contains a translation for your string like%0a%0a    'my English expression' => 'bla bla',%0a%0aand you want to override that, you need to use your XLSDV('nl',...) ''before'' calling the correspondent XLPage('nl',...). Otherwise, by using  XLSDV() ''after'' XLPage() - e.g. within a recipe that is included later in config.php - your translation will only work as long nobody defines 'my English expression' in that XLPage.
+time=1281089056