Gammon Forum : MUSHclient : International : How to localize MUSHclient messages into other languages

Log on

Gammon Forum

Entire forum

MUSHclient

International

How to localize MUSHclient messages into other languages

How to localize MUSHclient messages into other languages

It is now over 60 days since the last post. This thread is closed. Refresh page

Pages: 1 2 3

Posted by Nick Gammon Australia (22,975 posts) bio Forum Administrator

Date

Tue 12 Jun 2007 03:47 AM (UTC)

Amended on Wed 13 Jun 2007 02:18 AM (UTC) by Nick Gammon

Message

Version 4.09 introduces a preliminary attempt at Internationalization (i18n).

I encourage anyone that wants to see a localized version for their language to try to follow the steps described below, and make a version that displays some messages (at least) in their own language.

This version is by no means complete - it was done fairly quickly with a view to being a proof of concept. It is possible that some things were inadvertently changed for the worse. Perhaps some existing messages will not be displayed correctly. If that happens, please advise the exact thing you were doing, and if possible compare to an earlier version to find what the message used to say.

Things NOT changed

This version does not have any changes to the "resource" part of the executable, in particular menus and dialog boxes will still be in English, and there is no provision for changing them. That should be possible to do by editing the resource files (which are publicly available) and making new versions marked as being appropriate for a new locale. These (when available) can be merged into the existing executable, in future releases.

[Edit] See below - version 4.10 now allows this.

How to localize

You should find - as a subdirectory to where MUSHclient is installed - a directory called "locale". In that will be a file "Localize_template.lua".
Copy (or rename) that file to be xx.lua, where xx is your locale identifier. (eg. EN for English, ES for Spanish, DE for German, FR for French).
Check that MUSHclient has correctly deduced your locale by starting it up, and going to File -> Global Preferences -> General. Near the bottom corner is a new field "Locale code". Make sure that this agrees with the code you have chosen for the localization file (Eg. EN, ES, DE, FR). If not, change it. :)
Edit the localization file with a text editor that supports UTF-8 encoding. For example, Crimson Editor: http://www.crimsoneditor.com/

If you are using Crimson Editor make sure that the Document Encoding Type is set to UTF-8 Encoding (w/o BOM). See the Document menu -> Encoding Type.
Review the English messages, and make translations where you feel is appropriate.

For example, right near the start of that file are these lines:
```
-- DDV_validation.cpp:41
  ["This field may not be blank"] =
    "",
```
You can put in a translation by changing the empty string to show the translated version, like this (I did this with Google translate, so bear with me if it came out as nonsense):
```
-- DDV_validation.cpp:41
  ["This field may not be blank"] =
    "Dieses fangen kann möglicherweise nicht leer sein auf.",
```
Save the changed xx.lua file.
Close MUSHclient if necessary (completely, not just the current world).
Restart MUSHclient. At this stage it should notice the xx.lua file and process it. If there are syntax errors in it you will get a message now.
If you made the suggested change above, you can confirm it worked by going to the Connection menu -> Quick Connect. Hit <enter> without entering a TCP/IP address, which will trigger off the message above ("This field may not be blank").
You should now see the translated message instead.
You can now re-edit the xx.lua file and make further translations. Remember to save it, and restart MUSHclient, in order to test them.

Different sections in the localization file

The localization file is currently split into four different sections. Each consists of a Lua table, the key of each item of which is the original message (in English) inside MUSHclient.

The four sections are:

messages - these are "static" messages (error or advisory messages). They are static in the sense that they don't change at runtime, and thus can be translated as a unit. For example, the message "This field may not be blank" will always be exactly that.

Thus, the translation in the "messages" section is simply a string, which is the translated message.
formatted - these vary at runtime. For example, the message "Line number must be in range 1 to %i". In this case the upper limit varies, and thus the message cannot be translated into a static string.

For formatted message there will be a "replacement" sequence indicated by %x where x is a formatting character. Consult the string.format documentation inside MUSHclient for possible replacement sequences. For example, %s is a string, %i is an integer, and %f is a floating-point number.

Because some work may be needed to get a good translation, each message in this section calls a function, and the responsibility of that function is to do the translation, incorporating the variable fields.

Let us assume that we are translating into Spanish for the moment, and that a good translation would be "La línea número debe estar en la gama 1 a %i."

First, we locate the templated message:
```
-- GoToLineDlg.cpp:45
  ["Line number must be in range 1 to %i"] =
    function (a)
     
      return ""
    end,  -- function
```
The xx.lua file already has a function definition, and it has worked out that we have one variable, which it has named 'a'.

So, to translate it into Spanish we could do this:
```
-- GoToLineDlg.cpp:45
  ["Line number must be in range 1 to %i"] =
    function (a)
     
      return string.format (
        "La línea número debe estar en la gama 1 a %i.", a)
        
    end,  -- function
```
We use string.format, which is a Lua function that lets us imbed things into a string, and supply the variable (a) as an argument.

Having made this change, and restarted MUSHclient, we can go into the inbuilt notepad, press Ctrl+G to "go to line", and enter a line out of range (eg. 1000). You should then see the translated message appear, with the correct range incorporated into the message.

Some messages may require more work, for example something like "loaded %i alias%s". Here we have a number (eg. 10), and if the number is not 1, then the second variable (%s) would have "es" in it, so the message would read "loaded 10 aliases".

To translate that into another language, you would have to look at the variable which has the number in it, and take appropriate steps to "pluralize" the noun.

If one of these translation functions has a run-time error (for example, concatenating a string with nil), then a dialog box will appear at runtime, at the moment that the message would have appeared, describing the nature of the error. Then, since the function has failed, the original message, in English, will be displayed.
times - these are for formatted date/time strings. You may need to look at the source code to see the context . For example:
```
-- doc.cpp:6767
  ["--- Connected on %A, %B %d, %Y, %#I:%M %p ---"] =
    "",
```
For the "times" messages the fields starting with "%" are date/time fields. See the documention for os.date for an explanation.

You may want to translate any English words (eg. "Connected on") plus revamp the order in which the date/time fields appear.
headings - these are generally one-word fields which are used in the various "list" dialogs (like the list of plugins). By changing the translations here you can change the column headings. For example you might change "Author" to "Autore" (Italian).

Thus, a changed entry might look like this:
```
-- PluginsDlg.cpp:105
  ["Author"] =
    "Autore",
```

Notes

Any entries you don't change will continue to appear in English. Thus, if you don't mind a bit of a mixture of English and your chosen language, only translate the messages that appear often enough that you wish they were translated.
Since the entire localization file is a Lua source file, feel free to use comments, make special functions to handle things that are done often (like making words plural), and generally organizing it the way you want to.
You have access to the standard Lua libraries, plus MUSHclient extension libraries "rex", "bit", "utils", and "bc".
You can use the information about the source file, and line number, to read the MUSHclient source, and find out more about the context in which a particular message appears.
Some messages are displayed in the output window. If you are using Unicode characters then make sure that you have UTF-8 enabled in the world configuration "Output" section, and that you have chosen a font that displays Unicode characters.
Feel free to post messages announcing your intention to translate into a certain language. You may find other people interested in collaborating with you - for example, to each do a part of the file.
Please do not spend weeks of work translating just yet - the format of the file may be fine-tuned yet, depending on comments we receive from the initial attempts. Also, the file is very likely to be expanded with new entries.
Do not change the "key" text - the stuff inside the square brackets. If you do so, it will no longer match, and become ineffectual.
Any messages that are not in the table at all, or return an empty string, will default to the original English message being displayed.
There are probably parts of MUSHclient that have not yet been converted to use the translation process. Please advise any such messages that you think should appear in the localization file.

- Nick Gammon

www.gammon.com.au, www.mushclient.com