This plug-in module allows the system administrator to customize system messages that are printed out by various components and plug-ins. System messages are those messages and other strings of text that are "hard-coded". ("Content", on the other hand, refers to text that is stored in the database, and has its own methods for handling other languages.)
The usual application is to translate system messages into alternate languages so that messages, control panels, prompts, errors, and buttons can be "Internationalized". However you can also employ this feature simply to change messages that you don't like.
ExSite allows for different "versions" of any piece of text or content. Each version has a name (eg. "French"). You use this name to select alternate versions. It is normal to use the native version of a language name, so that it is more recognizable in language selectors to its native speakers. (So, "Français" would be a better way to specify our example.)
If you want your system to support multiple languages, you must perform two simple configurations:
First, you must define your complete list of alternate versions.
Your default version (normally "English") should not be included this list.
Your list of alternate versions is taken from the datatype
list:version
, which is defined in
cgi-bin/dbmap/.datatype
. Add a line to this file (or
edit the existing line), with three tab-delimited fields like
this:
list:version select Français
This example sets up a bilingual site in English (default, not shown) and French (shown). If you want more than two languages, add more to the end of this line, separated by the bar character "|". There is no limit to the number of languages that you can support, for example:
list:version select Français|Español|Deutcsh
If the language names require non-ASCII characters, add them to this
file in the same character encoding you use for ExSite. This is UTF-8 by
default (although you can use any character encoding by setting the
configuration parameter charset
).
Now you should put the system into another language mode so that it will try to use messages in the alternate languages. There are two ways you can change the language mode:
default_version
to one of your selected languages, and then
interact with the administrator tools.)
Every time the system tries to output a system message in one of your alternate languages, but cannot find an appropriate translation, it falls back on the English version, and logs the message in the message dictionary for the attention of a translator. This means that you simply have to use your system for a while, and it will automatically log for translation every message that sees common usage.
In administrator control panels, failed translations are highlighted like this so you can spot new translatables as they appear. You can add a CSS class "NoTranslation" to your website stylesheet if you would like the same feature on your regular webpages.
Once you have accumulated a good number of messages in your translation logs, you can use the System Messages plug-in to perform your translations.
Launch the plug-in, select the language/version you want to
translate, and it will show you a list of messages that it has tried
unsuccessfully to translate into your preferred language. Click on
the buttons to translate each
message.
The translation form shows the default (English) message, with a text area to enter the equivalent in your selected language. After you submit a translation, it will disappear from the list of required translations, and you can move on to another message.
Some messages contain tags to insert other data. These might look something like this example:
Please contact the system administrator, at [[admin_email]].
That means that some other data (in this case, an email address)
will be substituted into the [[admin_email]]
position of
the message at a later time. When translating such messages, do
not translate/change those tags, or the system will not know where
to put the data.
The procedure above will identify the most-viewed messages quickly, but some rare messages (especially error messages) will get missed. Over time, ExSite will slowly uncover more of these messages. Whenever a new message is found, it will be displayed in the special style that indicates a missing translation. You can take this as a hint that you or your translator can visit the System Message plug-in to touch-up the translations.
If you ever need to correct or update a translation, simply use the search tool in the System Messages control panel to find the message of interest.
If system messages get changed or updated, they will usually appear as entirely new messages in the dictionary, requiring translation all over again.
Code must be written to support internationalization to make use of this feature. If not, then the messages will only output in their original hard-coded version. If you see a message on a system screen in the wrong language, then it supports internationalization if it has been restyled to indicate a missing translation.
To upgrade messages in the code to support internationalization,
simply enclose the message string in $msg{...}
. For
example, the old message:
return "Permission denied - you do not appear to be logged in!";
should be rewritten as:
return $msg{"Permission denied - you do not appear to be logged in!"};
To allow for messages that include substituted values from external sources, you can use a method like this:
Old:
return "Please contact the system administrator, at $admin_email."
New (method 1):
return $msg{"Please contact the system administrator, at"}." ".$admin_email;
New (method 2, using ExSite::Misc::substitute()
):
return &substitute( $msg{"Please contact the system administrator, at [[admin_email]].", { admin_email => $some_email_address } );
Method 1 gives the translator a sentence fragment to translate. Sometimes this can be insufficient to make a good translation, especially if the sentence structure should be different in the other language. The 2nd method will appear as a more complete message in the translation tools, with substitution fields clearly marked. This may give the translator more flexibility for a correct translation.
In any case, do not include the actual substituted values in
$msg{...}
or you could end up with many variations on a
single message, all requiring individual translation.