{=
  include("docs.util");
  start_docs_page(docs.technical_manual.page_titles.languagemodules);
=}

<p>All text displayed by $PRODUCT_NAME can be modified, customized, or translated by modifying $PRODUCT_NAME's Language Module files. This includes the links at the top of the interface, the name of table headers in the reports and this documentation. Language modules are text files, located in the languages sub$lang_stats.directory of the LogAnalysisInfo sub$lang_stats.directory. Documentation is separate, in the docs sub$lang_stats.directory, which contains all the text $PRODUCT_NAME ever displays.  The documentation files can be duplicated, renamed, and modified to provide translations into any language. By modifying the language modules, or creating your own, you can translate $PRODUCT_NAME's interface into any language, or you can customize any text that $PRODUCT_NAME generates. Some language translations already exist; visit the $PRODUCT_NAME web site for more information.  If you need translations into other languages, that will be under your own discretion.</p>

<p>There are four language module files which together define every bit of text $PRODUCT_NAME ever generates (plus, there are the documentation files).</p>  They are: </p>
<ul> 
  <li> <p><b>The statistics reports - lang_stats.cfg</b>:   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 $PRODUCT_NAME's statistics into any language.</p>
  <li> <p><b> The administrative interface - lang_admin.cfg</b>:.  This includes the text of the profiles list, the configuration page, the Scheduler and other administrative pages.</p>
  <li> <p><b>The options interface - lang_options.cfg</b>: The names and descriptions of all of $PRODUCT_NAME's options.</p>
  <li> <p><b>The error messages interface - lang_messages.cfg</b>: The error messages and debugging output.</p>
</ul>

<p> For example, if all you need is a translation of the statistics you can use the English administrative interface, but you 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, or other features in a language other than English, you will need translations of the lang_admin, lang_options, and lang_messages modules.</p>

<h3>Creating a New Language Module</h3>
<p>To begin translating, duplicate the "english" $lang_stats.directory in the languages $lang_stats.directory of the LogAnalysisInfo $lang_stats.directory, and change its name to the new language and then edit the files inside it.  To switch languages, change the language specified in the preferences.cfg file of the LogAnalysisInfo $lang_stats.directory to match the name of the $lang_stats.directory you created.</p>

<h3>Language Module Syntax</h3>
<p>Language modules are configuration files, and their syntax is described in {=docs_chapter_link('configfiles')=}.</p>

<p>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.</p>

<h3>Debugging Language Modules</h3>
<p>When you write a language module, you must be precise in the syntax  and even a small error, like an unclosed quote, can make the entire file unreadable by $PRODUCT_NAME. This may result in a situation where $PRODUCT_NAME can't even report the error properly because the error message is in the corrupted language module.</p>
<p>This sort of a problem is difficult to track down, so a special feature of $PRODUCT_NAME lets you debug language modules easily. It requires a command-line version of $PRODUCT_NAME, and you must change the name of the $PRODUCT_NAME executable so that it contains the characters "lmd" (that stands for Language Module Debug) -- for instance, you might change the name of the program to <code>$(PRODUCT_EXECUTABLE_DOCS)_lmd</code>.  Once you've done that, run $(PRODUCT_NAME).  When it notices that its name contains "lmd", it will start generating information about the language modules it's reading, including 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.<p>

<h3>Special Language Module Variables</h3>
<p>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.</p>  Some special variables are also available:</p>
<ul>
  <li> <p>RUNNING_USERNAME: The name of user $PRODUCT_NAME is running as.</p></li>
  <li> <p>PRODUCT_NAME: The name of $PRODUCT_NAME ("$PRODUCT_NAME" by default, but different if the product has been relabelled or white-labelled).</p></li>
  <li> <p>PRODUCT_EXECUTABLE: The name of the $PRODUCT_NAME executable file ("$PRODUCT_EXECUTABLE" in this case).</p></li>
  <li> <p>PRODUCT_EXECUTABLE_DOCS: The name of the $PRODUCT_NAME executable file, as used in documentation where a generic executable name is more useful than the actual one ("$PRODUCT_EXECUTABLE_DOCS" in this case).</p></li>
  <li> <p>PRODUCT_URL: A link to the $PRODUCT_NAME home page ("$PRODUCT_URL" in this case).</p></li>
  <li> <p>COPYRIGHT_HOLDER: The holder of the $PRODUCT_NAME copyright ("$COPYRIGHT_HOLDER" in this case).</p></li>
</ul>

{= end_docs_page() =}