Language Modules--Localization and Text Customization

All text displayed by Sawmill, from the links at the top of the interface, to the name of table headers in the reports, to this documentation, can be modified, customized, or translated by modifying Sawmill's Language Module files. Language modules are text files, located in the languages subdirectory of the LogAnalysisInfo subdirectory (documentation is separate, in the docs subdirectory), which contain all the text Sawmill ever displays. These can be duplicated, renamed, and modified to provide translations into any language. By modifying the language modules, or creating your own, you can translate Sawmill's interface into any language, or you can customize any text that Sawmill generates. Some language translations already exist; visit the Sawmill web site for more information. If you need translations into other languages, you will need to do the translation yourself.

There are four language modules files which together define every bit of text Sawmill ever generates (plus, there are the docs). These are:

If all you need is a translation of the statistics (i.e. if you can use the English administrative interface, but need to provide statistics in the native language of your clients), then you only need a translation of the lang_stats module. If you need to be able to use the profile list, configuration page, Scheduler, etc. in a language other than English, you will need translations of the lang_admin, lang_options, and lang_messages modules.

Creating a New Language Module

To begin translating, duplicate the "english" directory in the languages directory of the LogAnalysisInfo directory, and change its name to the new language. Then edit the files inside it. To switch languages, change the language specified in the preferences.cfg file of the LogAnalysisInfo directory to match the name of the directory you created.

Language Module Syntax

Language modules are configuration files, and their syntax is described in Configuration Files.

When translating or customizing a language module, you should not change the names of variables--those must remain exactly as they are. Only the values should be changed.

Debugging Language Modules

Writing a language module can be tricky, because a small error (like an unclosed quote) can make the entire file unreadable by Sawmill, sometimes resulting in a situation where Sawmill can't even report the error properly because the error message is in the corrupted language module.

This sort of a problem is difficult to track down, so a special feature of Sawmill lets you debug language modules easily. It requires a command-line version of Sawmill, and you must change the name of the Sawmill executable so that is contains the characters "lmd" (that stands for Language Module Debug) -- for instance, you might change the name of the program to sawmill_lmd. Once you've done that, run Sawmill. When it notices that its name contains "lmd", it will start generating information about the language modules it's reading, included the tokens it's processing and the name/value pairs it's finding. It is usually a simple matter to examine the output and see where the erroneous quote or bracket is.

Special Language Module Variables

Language modules are configuration files, and can contain references to any other configuration variables, using the standard dollar-sign syntax. Any variable in the configuration hierarchy can be referenced in this way. Some special variables are also available: