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:
-
lang_stats: The statistics (reports). This includes the names of the reports, the names of the fields, the instructions, the names of the options, the table headings, and more. This small language module is all that must be translated to translate Sawmill's statistics into any language.
-
lang_admin: The administrative interface. This includes the text of the profiles list, the configuration page, the Scheduler, and other administrative pages.
-
lang_options: The names and descriptions of all of Sawmill's options.
-
lang_messages: The error messages and debugging output.
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:
-
RUNNING_USERNAME: The name of user Sawmill is running as.
-
PRODUCT_NAME: The name of Sawmill ("Sawmill" by default, but different if the product has been relabelled or white-labelled).
-
PRODUCT_EXECUTABLE: The name of the Sawmill executable file ("sawmill" in this case).
-
PRODUCT_EXECUTABLE_DOCS: The name of the Sawmill executable file, as used in documentation where a generic executable name is more useful than the actual one ("sawmill" in this case).
-
PRODUCT_URL: A link to the Sawmill home page ("http://www.sawmill.net/" in this case).
-
COPYRIGHT_HOLDER: The holder of the Sawmill copyright ("Flowerfire, Inc." in this case).