This is a system message translation tool, for displaying any text that is hard-coded. System messages are coded in English, and in a default installation will simply be echoed back to the user.
If alternate languages are enabled by either changing the default system version to something other than ``English'', eg.
default_version = Deutsch
or by viewing a page whose version is set to something other than English, then we we will try to find alternative (translated) system messages in the preferred language. If found, we return those instead; otherwise we return the English message (wrapped in ``NoTranslation'' CSS markup), and log the missing translation for the attention of translators.
To output a message in the preferred language, use:
$msg{'English message'}
If the message contains data substitutions, it is best to use a template so that the message only needs to be translated once for all values of the data that might be substituted into it:
&substitute($msg{'Error on page [[page]]'},{page=>"index.html"})
In both cases, the message is simply echoed if the user prefers English or if no translation is found.
To output a message that is bilingual (English plus the alternate language, eg. ``English / Anglais''), use:
(tied %msg)->bilingual('English message');
If no translation exists, the bilingual function returns only the original English message. If a translation exists the translated part is wrapped in ``Bilingual'' CSS markup.
Use the SysMsg plug-in to manage your message translations and build your multilingual dictionaries.
When translating templated message with substitution fields, do not translate the substitution markers. For example, the following message:
'File not found: [[filename]]'
should leave the '[[filename]]' part the same in the translated message. However, it can be moved to different part of the message if the grammar rules of the alternate language require it.
The simplest way to build a dictionary is to set the system to use the alternate language as the default, and/or to create some alternate language pages.
Then, exercise the system under the alternate language. The system will begin logging all messages it encounters that do not have translations. It may not find all such messages because many will correspond to obscure error conditions that are not reached in normal operations, but it should find all of the typical messages that the system makes use of.
Then, switch your default language back to English (simply by commenting out the default version setting in your config file). You can now visit the SysMsg tool to see all the messages that were logged as requiring translations.