                             TRANS
                   The Source Code Translator
                          Release 1.1


                             Overview
                             --------

     Do you need to translate an application to another language? Do you
localize your applications to other countries?

     TRANS is a source code translator. A very useful tool to localize
applications to other countries, using their respective language.

     With TRANS you will not have to change any source code lines. Write
the code in your native language, and let TRANS perform any translation
necessary.

     TRANS remembers! When you change your original source code, only new
or modified text needs to be re-translated.

     TRANS operates with ASCII source files written in C, C++, DCL,
LSP,... and so on.  General speaking, TRANS will recognize any ASCII file
with the translation text enclosed in double quotation marks, like
"\nPlease, Enter value:"   or  "C:\\MSDOS.SYS" , with no compiler or
language dependence.

     TRANS is able to translate, in a single pass, any number of files of
any length, reducing considerably the costs of translation . All files to
be used are specified in a special project file, called Control File.

     If you are using the Shareware Demo version, TRANS will only admit
projects up to a 10 file maximum, and will only process the first 5Kb of
each one. Registered releases do not have these limitations, and because
TRANS runs on extended mode, any file up to 32MB can be processed.


                        System requirements
                        -------------------

TRANS requirements are:

     * MS-DOS 3.3 or higher.
     * 80386 or higher processor
     * At least 1MB of RAM. Naturally, this quantity will increase according to the size of
     the   project.
     * 1MB space available on Hard Disk.
     
     Microsoft Windows users will have no problems, because TRANS is DPMI
     0.9 fully compatible, so you can run TRANS on a DOS window, performing a
     translation in batch mode.




                        Calling TRANS
                        -------------

     TRANS is a DOS command line application, running where the DOS prompt
is available, or inside a complex batch BAT process.

     Calling TRANS is easy:

     TRANS < Control File > < Operation >

     Neither Control File nor Operation are optional parameters. Both need
to be specified.  The  < Control File > parameter designates an ASCII file
with a special format. This file has all the project information which is
explained in detail further on in this document.

     The < Operation > parameter is able to take one of the two 
following values:

     READ: This operation mode takes all the text enclosed in double
     quotation marks and stores it in the Translation File. This is the basic
     pre-translating operation.
     
     WRITE: This operation mode translates all the source text files,
     reading from the Translation File.
     
The standard translation process with TRANS is:

     1- Create a Control File containing all the information about source
     files and Translation File name.

     2- Call TRANS with the name of that Control File as the first
     parameter and READ as the second parameter.
     
     3- Give the Translation File to a professional translator (This file
     will be a list of all the messages that have to be translated to another
     language, and is therefore very easy to understand for computer
     illiterates!).
     
     4- Call TRANS with the original Control File and WRITE mode using the
     modified Translation File.
     
     As you know, an application will need to be updated whenever
     necessary, so, when you add or remove text from your source files, thanks
     to TRANS, only the new text will need to be translated, making it a very
     productive tool to update localized applications.




                         Activity File
                         -------------

     Whenever  TRANS performs an operation, it registers all relevant
information to a file called TRANS.LOG. It is very important to consult
the results of this file when the task involves large batch operations.



                         Control File
                         ------------

     The Control File is an ASCII text file used to store all the source
file names, and the result file, called Translation File.

     TRANS will expect a file with the following structure:

Heading line
------------

     The first line consists in a heading composed of the following
text (without quotation marks):

     #TRANS 1.0

Translation File name
---------------------

     The Translation File to be processed is specified here, under a
section header [Text].  The Translation File must be specified with its
complete path.  For example:

     [Text]
     U:\PATH\FILENAME.TXT

Source File names and paths
---------------------------

     Under the section header [Files] you can specify all paths and files
to be processed by translation. The path line indicates where the files
are to be found and later processed, and in the subsequent lines these
files are named.  This process can be repeated as many times as considered
necessary.  For example:

     [Files]
     U:\PATH_ONE
     SOURCE1.C
     SOURCE2.C
     SOURCE3.H
     U:\PATH_TWO
     SOURCE4.C
     U:\PATH_TWO\SUBPATH
     SOURCE5.H
     SOURCE6.C



                         Translation File
                         ----------------

     The Translation File is updated automatically by the program, or
created if not previously in existence, each time that the program is
executed (with READ or WRITE).

It is composed of the following fields in the order that they appear below:

Heading line
------------

     It is formed by the string:

          #Text file for TRANSLAT v1.0

     followed by the date and hour of the last modification.

File source listing
-------------------

     This begins with the next identifier: 

          [Source]

     Then, the section presents all the sources in which to look for text
     strings. Each line is composed in the following way:

          <Source IDnumber>,<Source path>,<File Date>,<File Time>

Descriptions:

     Source ID number: An ordinal file index. This index is used in all
                       the Translation Files as a reference.

     Source Path:      The file name with its complete path.

     File Date:        Date of the last file modification.

     File Time:        Time of the last file modification. N.B. File Date and
                       Time information is an excellent way to distinguish
                       files which may later need translation by an
                       updated application.
     
Languages section
-----------------

     Starts with the next identifier: 

          [Languages]

     and contains two lines:

          Source: You must specify the source language.

          Target: You must specify the target language. Both parameters will be
                  useful to a human translator, however ignored by TRANS.
     
For example:

     [Languages]
     Source=English
     Target=Spanish

Text section
------------

     Starts with the next identifier: 

          [Text]

     and contains all the message strings found in the source files
     (sources), and the translation strings written by the professional
     translator (targets).

Each source line looks like this: 

     <String>,<Translatable>,<Length>,<File ID>,<Line>,<State>

Definitions:

     String:       Indicates the string found, enclosed in quotation marks.

     Translatable: [TRANSLATE|IGNORE] Indicates if it should be translated,
                   TRANSLATE, or not, IGNORE. By default, TRANS places
                   TRANSLATE on all strings when reading the first time.
                   You must change it to IGNORE if a string is not text,
                   but a literal.

     Length:       [VAR|FIXED] Indicates if the length of the original
                   string must be equal to that of the translated one:FIXED,
                   or it can be of any length: VAR.
                   You must specify FIXED in this field if you want to
                   ensure TRANS rectifies with spaces or abbreviates the
                   translated text to fit into the fixed memory string
                   allowments.

     File ID:      Indicates the file ordinal index where the string
                   appears for the first time on the source reading
                   sequence. For further information see File Source Listing.

     Line:         Refers to the line number where the string is found
                   within the source file referred by File ID. You must
                   use this information to locate obscure strings and see
                   them in their proper context.

     State:        Because the Translation File is updated each time you
                   translate your source files, the strings you may have
                   eliminated will be considered by TRANS in the following
                   way. Any string not found in the original source files
                   will be marked with OLD and existing strings with ACT.
     
The target lines must be added by the human translator, inserting a new
line inmediately after the source line, then, enclosed by quotation marks,
the target text to be used.

For example:

      "New Value:",TRANSLATE,VAR,3,154,ACT
      "Nuevo Valor:"

where  "New Value:"  is the source line and  "Nuevo Valor:"  is the target
written by the human translator. Notice that the target line has no other
information but the text itself.

No empty lines must be used.




                         The Translation Process
                         -----------------------

In order to translate a complete application, a user must  follow these steps:

     1- Create a translation directory to store your original text sources
        to be translated.  Copy all your source files to this directory. It is
        advisable to make a backup copy of your original source files to
        avoid any accidents!

     2- Create a Control File to translate your application. It must
        contain all the source files and path of the newly created translation
        directory, and the name of the Translation File to be created..

     3- Call TRANS with the Control File name and then the READ operation.

     4- TRANS will create the Translation File with the file name you have
        indicated on the Control File. Edit it in the following manner:

        4.1- Mark all the lines you do not want translated with IGNORE.

        4.2- Mark all the lines you want the original length maintained
             with FIXED.

        4.3- Complete the [Languages] section.

        4.4- The human translator must now add the translated lines. The
             translation text must be enclosed with quotation marks and
             placed on the line following the original one.

     5- Call TRANS again, with the same Control File, but this time use
        the READ operation. TRANS will change your source files in your
        translation directory into new translated source files.

     6- Compile the translated source files and check the texts
        consistency. If any string has not been properly translated then
        repeat steps 3 to 6 until completed.
     
     If you want to modify your original application, then only steps 3 to
6 need to be repeated with these new source files. TRANS will recognize
all the text except the new strings, which will now undergo the
translation process . If after this some of the original strings have
shown minor changes from the previous translation, search the OLD marked
strings on the Translation File to rectify.

     All these steps can be done automatically by making a batch file that
copies the translating process.

     We recommend you to create a different directory for each language
you intend to translate the application(s) into, if you are using
multi-lingual software.




                         Example provided
                         ----------------

     There is an example included with TRANS. It's supposed that you have
the original source files in the following directory:

     C:\TRANS\SOURCE

and you want to create a translating directory (ie English to Spanish)

     C:\TRANS\ENGSPA

If you don't use this directory structure, you must modify the ENGSPA.CTL
file to address the correct path.

The file READ.BAT will do the 2nd and 3rd steps (explained on Translation
Process). After translating the text in

     C:\TRANS\ENGSPA\ENGSPA.TXT

you can use WRITE.BAT to translate all the source files and compile.
The Control File provided is 

     C:\TRANS\SOURCE\ENGSPA.CTL


------------------------------------------------------------------------------
