[Developers] Multiple Language Class

Note: download below

Also, I do realize that this is a simple class and that anybody could easily see how to use it by looking at the code, but I felt like writing this example. It's not perfect, and it doesn't cover every tiny use of the class, but it gives you the main idea.

As requested by MenthiX in this thread, I have created a class for handling multiple languages and translations in scripts. It is easy to use and can support as many languages as you'd like. It also can automatically translate windows for you. With the MLC, you can easily make a combo-box in an options window change the language of your entire script. The Multiple Language Class is based on external files.

The Language Files folder path/name can be changed, but is referred to by Language Files throughout this post.

The Multiple Language Class by default looks for .txt files in a folder called Language Files relative to your script's directory. This can be changed on initialize, or any time during the program. Inside the Language Files directory will be all the language definitions, and one more folder. This will be called Windows. The Windows folder is always located inside of the Language Files folder.

For example, let's pretend we have a language file for English. This is called English.txt, assuming we have not changed the file extension. For the rest of the post, we will be using a non-existent script that will upload any file to a server. Our English.txt will look like this:

quote:
//The options window.
Server:
Username:
Password:
//The 'upload a file' window.
Please select the file you would like to upload.
//Command tooltip
Upload a file to the specified server.

Notice how there are comments in the file. These will be completely ignored by the class. The class does not ignore /*...*/ comments, only // comments.Each line that is not blank and not a comment is recognized as a string. Now, we want a Spanish translation for users, so we create Spanish.txt. Each string is lined up with the corresponding string in the other file(s). Since they are ignored, comments do NOT need to be aligned. Note: these are translated with Google. They might not be accurate.

quote:
//The options window.
Servidor:
Nombre del usuario:
Contraseña:
//The 'upload a file' window.
Seleccionar por favor el archivo que quisieras upload.
//Command tooltip
Upload un archivo al servidor especificado.

Now our languages are set up. Next, we need to define the windows so they can be automatically translated. For this example, I'll only show the options window. In the Windows folder, we create another .txt file containing a list of controls. The actual window's XML shows that the window's ID is WndOptions, so we call the text file WndOptions.txt. Then, we see inside the XML that there are three controls: LblServer, LblUsername, and LblPassword. So here's how our text file is set up.

quote:
LblServer
LblUsername
LblPassword

Now we are ready to actually start using the class. Place Languages.js with your other script files, and then you can start using the code. You will need to create a global variable for the Languages object.

code:
var Languages;
function OnEvent_Initialize(MessengerStart){
Languages = new LanguagesClass(BaseLanguage,TranslationLanguage,Path,Extension);
}

BaseLanguage - a string representing the base language. Most likely English, or whatever the author is most comfortable in. This is the language used to specify what strings you want the translation of.
TranslationLanguage - another string representing the language that the class will give translations in.
Path - Optional. Specifies the name of the Language Files folder, if you change it.
Extension - Optional. Specifies the file extension to be looked for.

For this example, I'm translating the script to Spanish, with English as the base language. It uses the default path/extension, so I use this code:

code:
var Languages;
function OnEvent_Initialize(MessengerStart){
Languages = new LanguagesClass('English','Spanish');
}

To get a translated string, you use:

code:
var MyTranslatedString = Languages.Translate(String);

String - the string to translate in the base language.
You can also use:

code:
var MyTranslatedString = Languages.String(String);

Using this method, in the OnGetScriptCommands event, you can get the translation of the tooltip specified earlier:

code:
function OnGetScriptCommands(){
var commands = '<Command>';
commands += '<Name>upload</Name>';
commands += '<Description>' + Languages.Translate('Upload a file to the specified server.') + '</Description>';
commands += '<Parameters/>';

To create the options window, we use the CreateWnd function. It has the same parameters as the default Plus! one:

code:
Languages.CreateWnd('Windows.xml','WndOptions');

This will create a window and automatically translate all the controls' text listed in the file for the window.

To set the translation language at any time:

code:
Languages.SetLanguage(Language);

Language - String representing the name of the new language

To set the base language at any time:

code:
Languages.SetBaseLanguage(Language);

Language - String representing the name of the new language

To set the folder path at any time (can be used to make multiple language sets):

code:
Languages.SetPath(Path);

Path - String representing the name of the new folder

To set the file extension at any time (can also be used for multiple language sets):

code:
Languages.FileExtension = Extension

Extension - String representing the extension, without a period at the beginning.

To get a list of all the loaded languages, use the following, which returns an array:

code:
Languages.GetLanguages();

Finally, here's the download. All I ask is that you keep the header unmodified where it is.

Shoutbox

login | register | shoutbox