TWIG 2.6 Language Scripts
December 13, 2000

Intro
=====

    TWIG 2.6 introduces a new system for maintaining it's string files, this 
    was prompted to allow for the global strings definition file to be reduced
    to only those strings that were truly global.

    To achive this goal each feature in TWIG needs to define it's own set of 
    phrases that it requires to support the translations.

    Ensuring that this structure is managable and achives it's goals to reduce
    overhead several additonal scripts have been created, these scripts will 
    not be used by end users or administrators, but instead by the TWIG 
    development team.

    ***NOTE*** 
    Do not directly edit any string files other than the ones that reside in 
    setup/Strings/SourceFiles otherwise they will be overwritten the next time
    these scripts are run.

The Theory
==========

    The theory beind the lanaguage scripts is simple, seperate the translation
    information from the feature requirements.

    This allows the language maintainers to continue to update a single file 
    (that has no duplicates in it) but allows for the distribution to split
    these files up in to the required peices for better performance.

The Scripts
===========

    generate.strings.php3
	  Converts the files in setup/Strings/SourceFiles in to the individual
	  feature string files, which are outputed to setup/Strings/Output.
	
    populate.strings.pl
	  Is used to move the files from setup/Strings/Output to the
	  appropriate directories.

    strings.layout.php3
	  Supports 1, by defining what strings are required for each
	  of the features.

Running generate.strings.php3
=============================

    The is a PHP3 script which need to be run from your install directory, 
    once you have the page display up, you can generate the individual langauge
    files by simply hitting go.  

    You can optionally only generate a specific language by the drop down
    menu.

    Ensure that you have given the web server user permissions to write to and 
    create directories in the setup/Strings/Output directory or this will fail.

Running populate.strings.pl
===========================

    This is a quick Perl script to move the files generated by 
    generate.strings.php3 in to the right directories.  You need to run this
    script as a user who can write to the TWIG source tree that you are working
    on.

    By default this file assumes you are running on a Windows based system, you
    will have to edit this file to run it on a UNIX based system.  Around 
    line 25 you will find instructions on what to do.

strings.layout.php3
===================

    This file is at the core or the operation of the script system, it tells 
    generate.strings.php3 what strings to put in what files.

    It's format is based upon three arrays:

    1. $StringFiles
	This is a uni-dimensional array of the features that need string files 
	defined.

    2. $StringSections
	This is a uni-dimensional array of sections that are contained in 
	$StringLayout.

    3. $StringLayout
	This is a three-dimensional array that contains all the key names that 
	are required for each feature.

	The first dimension is the feature (as defined in $StringFiles[] ).

	The second dimension is the section (as defined in $StringSections).

	The third dimension is an increasing numeric index.

	For example:
	  
	  $StringLayout["admin"]["TWIGphrase"][0]		= "Accounts";

	defines the first reequired TWIGphrase index to be Accounts for the 
	admin feature.

Adding new TWIGphrases
======================

    In TWIG 2.5 and below, if you wanted to add a phrase to the translation 
    files you simply edited the files in lib/strings an you were done.

    TWIG 2.6 requires a bit more.

	1. edit setup/Strings/SourceFiles to add the new phrase
	2. edit setup/Strings/strings.layout.php3 and add a new
	   entry under the feature you want to add the phrase
	3. run generate.strings.php3
	4. run populate.strings.pl

    This ensures that the change does not get overridden the next time steps
    3 and 4 are executed.

Non-breaking TWIGphrases
========================

    Most TWIGphrases are used as menu options, entry box labels, and other
    such short phrases. The non-breaking space HTML entity ( ) is
    therefore desired to keep these short phrases together when a browser
    might otherwise split the words of the phrase over two (or more!) lines.

    Because of the heavy internationalization of TWIG, non-breaking spaces
    will not be found among the keys of a phrase. The reasoning for this is
    straightforward: some single words in English translate into multiple
    words in other languages. So, just because there wasn't a non-breaking
    space in the English version (which was only one word) a non-breaking
    space would certainly be desired in the translated language (where several
    words are required).

    When translating, please keep this in mind, and add non-breaking spaces to
    your language's phrases as necessary to keep a short phrase on one line.

    Some TWIGphrases are fairly long sentences, and are used as explanations
    or error messages. For these phrases, the non-breaking space is *not*
    desired.