To translate OpenEpi to a non English language (for the first time):
It should not be necessary to understand or work with the JavaScript code or HTML of the programs to do a translation.
OpenEpi translation works as follows:
Var T = new Array() ; //Defines an array called T.
T[“Enter New Data”]=””;
T[“Enter New Data”]=”Entre Datos Nuevos”;
The JavaScript file, AppHelper.js, contains functions called initTranslation( ), t( ), and TranslateHTML( ). The initTranslation function checks a cookie that is set by the Settings.htm program (Options/Settings on the menu) to indicate the users choice of language. It then loads the appropriate translation file(s) into memory, creating the T array corresponding to the desired language. The t function receives a phrase as t(phrase) and returns the corresponding value from the T array. Hence, if the phrase is “New Data” and the language is ES, t(phrase) may return “Nuevos Datos” to be used by the program. TranslateHTML(webdocument), when directed to a web document, extracts all the text items from the body of the document and sends them to t( ) for translation.
Within the programs, two categories of phrases are automatically sent to the translation function, t(phrase).
· All text phrases in the commands of the OpenEpi Input and Output languages, such as “title” and “newrow” are automatically sent to the t function.
· Components of the dynamically created main page of each application, including the Title, Authors, and Description variables in the application’s js file, are automatically sent for translation.
Some phrases in an application must be placed in calls to the t function, as in
Msg1= t(“This message pops up when a problem occurs” ).
When t is called, the translation for the indicated phrase is returned from the T array indexed by the phrase. If no such item exists or the translation has not been provided, the original phrase is returned. Phrases are filtered so that numbers are not translated. The translator has the option of ignoring words that should not be translated or of removing their entries from the file. Removing a line like T[“CDC”]=”” or leaving it alone simply means that CDC will not be translated. Neither choice will cause an error.
For translation of HTML document files such as those describing Demos and Exercises is done by calling the function translateHTML(HTMLdocument). The specified HTML page is automatically scanned by TranslateHTML and all text phrases are sent to the t( ) function for translation. If UpdateTranslation.hta is running, text phrases are placed in the EN.js (or other specified language.js file during an update). In the absence of UpdateTranslation, text phrases are sent to the language array T (loaded with the correct language by initTranslation( )), and the translated phrase is returned and displayed in the HTML page.
The program called UpdateTranslation.hta runs only on Microsoft Windows® computers, where it can be used to extract all the phrases for translation from a new or revised OpenEpi program. To run UpdateTranslation.hta, first unzip the OpenEpi files to a directory on the hard disk of a Windows computer. Find the UpdateTranslation.hta file in the directory where OpenEpi resides and double-click on its icon. You may see a threatening message about security, to which the answer is “Yes”. UpdateTranslation will then ask for the name of the language to be updated or created. Enter your choice—ES, for example-- and UpdateTranslation will then run the OpenEpi menu. If the file exists, it will be updated with new entries; if it does not, it will be created.
While the menu is run under UpdateTranslation as the top level window, the t function in the programs behaves differently than under normal conditions. If t(“my phrase”) finds a corresponding entry in the array, T[“my phrase”], it behaves as during ordinary display, returning either the value of T[“my phrase”] (perhaps “mi frase”), or “my phrase” if T[“my phrase”]=””.
If the programsearches for a phrase without a corresponding item in T, for example, “New Phrase”, and there is no T[“New Phrase”], then this item is appended to the end of the translation file. Hence exercising all the functions in all the programs once while UpdateTranslation.hta is running will place all the phrases in the programs that have been automatically or manually marked for translation into the translation file. The exception would be a phrase that occurs in an alert box that appears only under special conditions. Such a phrase can be inserted into the translation file manually, but the following will ensure that it is always translated. Suppose that the alert box signifies a rare event, as follows:
if (rareEvent) {Alert(“Very rare event occurred.”) }
Normally this would be handled by inserting a call to t( )
if (rareEvent) {Alert(t(“Very rare event occurred.”)) }
but it is unlikely that t will actually be called while UpdateTranslation is running. Hence, the solution is:
var msg1=t(“Very rare event occurred”);
if (rareEvent) {Alert(msg1); }
In the latter case, t will be called for “Very rare event occurred” every time the program is run, and the phrase will not be concealed from the translation mechanism.
What happens if a phrase is edited by the programmer? Suppose that “Very rare event occurred” is changed to “A rare event occurred”. The next time that the program runs under UpdateTranslation, the new phrase is appended to the file, leaving the old phrase and its translation in place. Although this may leave some “dead wood” in the file, it has the great advantage of requiring new translation only for the new phrases. There is no need to start translating from the beginning when a new version comes out. Of course, as with any computer operation, it is a good idea to back up your working files before running UpdateTranslation.hta.
Document files are in HTML format, although they may have originated in Microsoft Word or PowerPoint. Shorter documents, like the Demos and Examples files, whether dynamically generated or saved as HTM files, can be translated by calling translateHTML( ) as described above. Those that
are, are now contained in the directory BriefDoc.
For longer documents--those in the Documentation directory-- the best method for translation seems to be to put the translation in the same HTML file, with an anchor or bookmark indicating the language at the top of the translated text. When the Documentation button is clicked in the application, the language block indicator (e.g, “#ES” if language is set to Spanish) is added to the document reference. If the Spanish translation is found in the HTML document at the anchor named ES, the translation is displayed; if not, the display defaults to the beginning of the document—the one in the original language.
For example, when the user interface is written dynamically in Proportion.htm, the Documentation button links to:
ProportionDoc.htm#ES
When the ES anchor is present, the browser loads ProportionDoc.htm and jumps to the ES anchor at the top of the Spanish translation. If the ES anchor is not found, however, the browser displays the English translation at the top of the document. There are no errors or interruptions when the ES anchor is absent.
In translating longer document files, then, no new files are created (other than images perhaps), and translations in several languages can be found in the the same HTML file.
To allow a user to choose a new language translation, the options in the file called Settings.htm may need editing to include the new language choice. To see if the language choice is already available, examine the Language choice in the Options/Settings page to see if the language is already present. If not, edit Settings.htm to add the new language choice.
If you produce a new translation, please notify Andy Dean and/or Kevin Sullivan at the addresses given on the OpenEpi website, www.openepi.com, so that that the translation can be added to the website version of OpenEpi.
In inserting translated phrases, embedded quotation marks will cause problems and even lock up the system. Since the translations are enclosed in double quotes, single quotes can safely be used inside the phrases, but NOT DOUBLE QUOTES. If it is necessary to use double quotes, they can be preceded by a slash (\”) to tell JavaScript to ignore the meaning of the quote. The same can be done with other characters that may have special meaning to JavaScript. Strings (text phrases) must be on a single line, leading to some very long and awkward lines. A string can be broken into lines as follows, however:
T[“This is a very long phrase that exends beyond the right margin of the word processor”]=”Translation of very long phrase “+
“can be broken using a \+ and \” sign”;
It is also all right to break the line on either side of the equal sign. Note that a space between words must be included after the word
“phrase” above, or the word ‘phrasecan’ will appear in the translation.
If a translated JavaScript file seems to cause trouble, try running OpenEpi in a modern browser. After or while it is running, choose Tools|Web Development|JavaScript Console from the browser menu or right-click on the screen to find debugging or developer tools. This brings up a debugger that will often pinpoint syntax errors such as unpaired quotation markes. If this does not solve the problem, try commenting out suspect lines, such as those with special symbols, using // at the beginning of the line. Look for unpaired quotes, particularly with long lines, where it is easy to omit the closing quote. If none of this works, please feel free to ask the authors for help. We would like to know about translations, and to have them work correctly.