                             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 file 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

     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 ID number>,<Source path>,<File Date>,<File Time>

Descriptions:

     Source ID number: Is an ordinal file index. This index is used in all the Translation
     Files as a reference.
     Source Path: Is 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 allotments.
     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 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. Let us suppose you have the original
source files in the next directory (if you don't use this directory structure, you must to modify
the ENGSPA.CTL file to address the correct path):

     C:\TRANS\SOURCE

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

     C:\TRANS\ENGSPA

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

