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: ,,, 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: ,,,,, 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 textïs 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