eXtc Web Developer - M/Gatewaygradvs1.mgateway.com/download/multiLingual.pdfeXtc Web Developer’s Solution eXtc Web Developer removes all these problems and provides a very simple

eXtc Web Developer

Rapid Web Application Development for Caché

Multi-lingual Localisation Version 1.1 Background eXtc Web Developer is a rapid application development environment for building and maintaining Caché-linked web applications, running under a number of environments including CSP and PHP. The PHP implementation relies on, and makes use of the m_php gateway that allows PHP to communicate with Caché. One of eXtc Web Developer’s advanced features is that it allows you easily build and maintain web applications in multiple languages. It can also be used to automatically create and maintain localized versions of existing CSP applications. This document is a reference guide to eXtc Web Developer’s multi-lingual localization capabilities. Pre-requisites This guide assumes that you have read the eXtc Web Developer Overview, the Installation Guide and Tutorial documents. Note that multi-lingual localization is currently limited to CSP compilations.

eXtc Web Developer : Multi-lingual Localisation. Version 1.1: 07 October 2004. 2004, M/Gateway Developments Ltd. All Rights Reserved

1

The Challenges of Multi-lingual Localisation A major issue for web application developers who create applications for the international marketplace is the creation of versions of their application’s web pages in other languages. The critical issue is not the translation of the text in each web page per se: the major problem is how to deal with ongoing maintenance of and changes to the application. Each additional language into which the application is translated compounds the problem, and ongoing maintenance can quickly become impractical, or, at best, an increasingly slow and time-consuming exercise. The usual technique for providing multi-lingual capability is to replace hard-coded text within the HTML (or CSP/PHP) pages with a call to a procedure that retrieves the appropriate text from the database, in the desired language. A look-up table in the database contains the translated text for each phrase within the web application, and each phrase is allocated a unique ID. The problem is that this introduces a great deal of obscurity and complexity to the source PHP or CSP pages, so that it becomes almost impossible for the programmer to envisage what the section of the page he/she is working on will look like, without running the page to a browser. Modifications to the page that involve changes to text require the careful maintenance and management of the text look-up table. It is easy to define the wrong code within a page, and easy to end up with cross-coding confusion, particularly if a team of developers is working with different pages. Further, the same text used in different parts of a web application can have different contexts, so the translations can be different. This adds further to the complexity of managing and maintaining the text look-up tables. If a great many web pages are involved, then textual translation is most effectively carried out by employing specialist off-site translation companies. The problem is that their translations will be literal ones, without any reference to the context in which each phrase is actually used. This inevitably leads to a second step where the translated phrases are checked within the running application for contextual correctness. A serious problem is how the reviewer can reliably identify corrections that need to be made – eg instructions such as “the xyz page, third line down, second sentence” are easy to misinterpret, leading to further translation errors. Further, much of the text that is displayed on the web pages may be generated behind the scenes in programming logic, not in the HTML component of the pages. This further adds to the management headache. The problem is not a one-off issue. A web application is usually a constantly changing, evolving beast, with wording changes, re-branding, new pages etc happening all the time. As more languages are added, the available solutions quickly lead to a situation that is complex, time-consuming and costly to maintain.


2

eXtc Web Developer’s Solution eXtc Web Developer removes all these problems and provides a very simple yet effective solution to web application localisation. The really important part of eXtc Web Developer’s solution is that your web application designer continues to develop and modify the design pages in his/her native language. Nobody needs to do any explicit allocation of coding schemes – instead it is entirely managed by eXtc Web Developer’s compiler. Multi-lingual localization is a compiler option in eXtc Web Developer. If you select the option, the compiler automatically converts all the text that it finds in the design page to procedure calls in the compiled run-time page. The compiler can do this because text and attribute values are specifically identifiable in the XML DOM. The textual phrases that are found during compilation are automatically assigned a unique ID and added to a database of phrases that is managed by eXtc Web Developer. eXtc Web Developer provides utilities for exporting the phrase list (in totality or just updates) for translation, and for importing the translated translations. A special compilation mode can be selected that aids the translator who is performing the contextual review of the application’s translated pages. In this mode, the original native-language phrase and its associated ID will pop up on the page when the reviewer moves his/her mouse over the phrase. Unambiguous editing instructions can then be given, or, alternatively, ad hoc translations or modifications can be made immediately by the reviewer via the eXtc Web Developer Manager web application. At run-time, the procedure calls that were added to the pages will retrieve the text in the appropriate language if it’s available (defaulting to the native language if not). All that is necessary at run-time is for a reserved session variable (ewd_Language) to define the user’s language, and the appropriate translations will be used automatically.


3

Creating and running multi-lingual versions of your web applications Just follow the steps below. Note that multilingual translation will currently only work correctly for CSP compilations. Do not attempt to use it for PHP applications Step 1: Defining your default language Start up the eXtc Web Developer Manager application and select the Multilingual tab. You should see a page similar to the following:

Select the application from the drop-down list and click the Select button. You should now see a page similar to the following:

Click on the Languages tab, as instructed:

Add a language code, eg “en”. It is up to you to decide the language codes for your application. Add the language name associate with this code, eg “English”


4

Click the Update button:

You’ll see that this first language has been defined automatically as the default language.


5

Step 2: Compile the application in Contextual Review Mode Still running the eXtc Web Developer Manager web application, select the Compiler tab. The page should look something like this:

Select the Enable, review mode radio button next to the row that says Multi-lingual compilation. Click the Compile all pages button for the application you require. If you examine the CSP pages that have been created by the compiler, you will see that all instances of text within the pages have been substituted with a call to an API method – displayText^%zewdAPI() , eg: <span title="textid=559 : Hello World"> #($$displayText^%zewdAPI("559",0,"csp"))# </span> You will also find the êwdTranslation global has been created. This provides the look-up table of text codes to their associated text and translations. In the example above, eXtc Web Developer’s compiler has allocated a code of 559 to this instance of the phrase “Hello World”. Note that each instance of a phrase is allocated a unique code, irrespective of how many instances of that phrase have already been found. This is because each code can identify the page and location (defined using XPath) of the phrase. This allows automatic recognition of changes to the text in each page on subsequent re-compilations. If a phrase in a page can be found with the same text and same XPath, then the existing code is used. If not, a new code is allocated.


6

Now that the initial coding has been performed, you can actually run the application in any language you wish to define – however this will be somewhat futile to begin with, since, without actual translations available, the page will default to your native language (eg English). Step 3: Defining the language to which you wish to translate the text Click on the Multilingual tab again, Select the application you require and then select the Languages tab again:

Add the language code and language name, eg fr and French respectively, and click the Update button:

Step 4: Translating the text You have two choices:

• Export the text to an XML file for translation by a third-party • Add/edit translations directly into the eXtc Web Developer Manager

application


7

Exporting the text Click on the Export tab

At this stage it will not matter whether you select the Untranslated phrases only radio button or the All phrases one, since no translations have been made. Enter the file name and path of the file you wish to create and click the Select button

Provided the filename and path was valid (the path must already exist but the filename does not need to already exist), you should find that the phrases have been exported into the file in XML format. Structure of the Export file The structure of this file is as follows:

<translationExport> <configDetails application='cspTest' fromLanguage='en' toLanguage='fr'/> <sourceText textid='1'> Company </sourceText> <sourceText textid='2'> Address Book </sourceText> </translationExport>

The outer tag is the <translationExport> tag. Within this is one instance of the <configDetails> tag, an empty tag that defines:


8

• The source language code

• The destination language code • The application name

The main content of the file is represented by repeating <sourceText> tags, each identifying the associated ID, with the text node for the tag holding the associated untranslated phrase. This file can then be sent to the translation company. Structure of the Import File The translated text, created by the translation company, must conform to the following structure:

<translationImport> <configDetails application="cspTest" fromLanguage='en' toLanguage="fr"/> <translatedText textid='1'> Compagnie </translatedText> <translatedText textid='2'> Carnet d'adresses </translatedText> </translationImport>

The outer tag is the <translationImport> tag. Within this is one instance of the <configDetails> tag that must match the one that was sent in the export file. The main content of the file is represented by repeating <translatedText> tags, each identifying the associated ID, with the text node for the tag holding the associated translated phrase. Importing the translation file Click on the Import tag, and enter the file name and path of the import file:

Click the Select button. Provided the translation file structure was valid, the translated phrases will now have been imported and added to the translation look-up table. eXtc Web Developer : Multi-lingual Localisation. Version 1.1: 07 October 2004. 2004, M/Gateway Developments Ltd. All Rights Reserved

9

Entering Translations Directly into the eXtc Web Developer Manager An alternative approach is to enter translations directly into the eXtc Web Developer Manager. Click on the List/Edit tab:

Select French from the drop-down menu and select All phrases. Then press the Select button. You should see a page similar to the following:

You can enter translations directly into the Translated Text text box. Press the Update button next to the text to add the translation. If the phrase is a common one, and the translation applies to every instance of the phrase, you can add the translation to every un-translated instance of the phrase by clicking the Update All button instead. You can delete individual phrases from the system by clicking the Delete button. This should not normally be done unless the phrase is no longer used in its page. You will find that as you add translations, they are made available as short-cuts for other similar phrases. These mechanisms allow very rapid and easy maintenance of the translations for your application. eXtc Web Developer : Multi-lingual Localisation. Version 1.1: 07 October 2004. 2004, M/Gateway Developments Ltd. All Rights Reserved

10

Step 5: Running the application in multi-lingual mode Now that you have imported or manually added the translations for the text in your application, you can run the application. You will need to instantiate a session variable – ewd_Language in the application. You will probably do this when the user logs in and you obtain the user’s language from his/her profile. Alternatively you will set the language when the user explicitly selects the language from, eg a hyperlink on the initial page of the application. If you set the ewd_Language session variable to the language code for which translations are available, eg: do setSessionValue^%zewdAPI(“ewd_Language”,”fr”,sessid) ..then all phrases for which translations are available will be displayed in the selected language. Step 6 : Contextual Review If the application was compiled in Contextual Review mode, then each instance of text will have been wrappered in a <span> tag with an associated title attribute that contains the id and original text. When the application is run, the reviewer can simply roll his/her mouse over an item of text that has been incorrectly translated, and the original id and text will appear in a pop-up bubble:


11

The reviewer can either manually record the text id that needs to be amended, or he/she can enter the corrected phrase directly into the eXtc Web Developer Manager application as described earlier. Step 7: Post-Review Once the contextual review is complete, the application should be recompiled with the Enable, run-time mode radio button selected. The text codes will remain the same, but the <span> tags will not be added to the compiled pages, so the roll-over contextual review help will no longer be available. Making changes to pages The Design Pages are, of course, still in your native language. You can make changes to the pages, add, edit or delete text within them, and you can add and delete pages within the application. The compiler will automatically re-code any text that has changed in any way or that has been added. The revised version of the application can be run in a translated language, but any new, as yet un-translated, text will appear in the native language. You can export the new phrases to be translated, and import their translations, or you can use the eXtc Web Developer Manager web application to translate the amended phrases. You can opt to just see un-translated phrases, to make the task of ad-hoc translation easier and more efficient, and if you have new instances of previously translated phrases, you can automatically use the previous translations to save time and effort. Text defined in scripts eXtc Web Developer includes a very straightforward and effective way of managing and maintaining text that is defined within your scripts, and is integrated with the multi-lingual functionality described above. The trick is to use one of two API methods when defining text values, ie instead of:

S error=”This is an error message” S warning=”This is a warning”

..use:

s error=$$errorMessage^%zewdAPI(“This is an error message”,sessid) s warning=$$systemMessage^%zewdAPI(“This is a warning”,”warning”,sessid)

In fact the errorMessage() function is simply a call to: eXtc Web Developer : Multi-lingual Localisation. Version 1.1: 07 October 2004. 2004, M/Gateway Developments Ltd. All Rights Reserved

12

s error=$$systemMessage^%zewdAPI(“This is an error message”,”error”,sessid) In other words, it defines the messageType as being an “error”. The mechanics of the systemMessage() function is quite interesting and depends on a number of circumstances:

• When the function runs, if the application has been compiled with multi-lingual mode disabled, it simply returns the message unchanged, and no other processing takes place;

• If the application has been compiled in either of the two multi-lingual modes: o if the message is a new one for the specified messageType, then it is

allocated a text id and added to the êwdTranslation global records. It will then appear as an un-translated phrase in the eXtc Web Developer Manager. The message is returned unchanged because no translation yet exists;

o if a text id is found but no translation exists for the language in which the user is running, the message is returned unchanged;

o if a text id is found and a translation exists for the language in which the user is running, the translated phrase is automatically returned.

eXtc Web Developer is able to determine all these circumstances simply by being passed the text string and the sessid variable. If a message is changed in a script, then the next time it is run it will be allocated a new text id, unless it matches an already translated phrase for the specified messageType.


13

Adding Multi-lingual Capability to Existing CSP Applications eXtc Web Developer’s multi-lingual localisation can also be used for existing CSP applications. All the same mechanisms described in this guide are available for existing CSP applications, without making any physical changes to the pages that make them up. The steps are as follows: Step 1: Copy the CSP pages and rename them as .ewd Design Pages

• You’ll need to have installed and configured eXtc Web Developer and defined an application root directory and a CSP output root directory.

• Create a sub-directory of the eXtc Web Developer application root directory

with an appropriate name and copy your CSP application’s CSP pages into it.

• Rename these files to have a file extension of .ewd instead of .csp Step 2: Configure the application’s multi-lingual languages

• Follow the earlier instructions to define the native language and any foreign languages needed for the CSP application. New languages may be added at any time in the future.

Step 3: Compile the application in Multi-lingual Review Mode

• Follow the instructions described earlier in this guide to compile the application in multi-lingual, contextual review mode.

• eXtc Web Developer will notice that none of your existing CSP pages include

an <ewd:config> tag, so will automatically invoke its pass-through mode, and will skip immediately to its multi-lingual processing.

• The compiled, processed pages will be output to the appropriate subdirectory

of the CSP output root directory. It automatically uses the same subdirectory name that you used for the application’s source Design Pages. Note that the CSP pages that are created conform to the XHTML standard, another interesting side effect and benefit of processing through eXtc Web Developer;

• All the text within the application will have been processed as usual, assigned

text ids and added to the êwdTranslation global records. All the standard multi-lingual translation mechanisms can now be used to export un-translated phrases and import translations. Until translations exist, the converted CSP application will display all its text in the native language as usual;


14


15

Step 4: Define the run-time language and run the application

• You will need to make one minor amendment to your existing CSP application’s logic in order to run in a translated language. You must set, in an appropriate place in one of the first pages of the application, the session variable ewd_Language. You can do this in a number of ways. Let’s imagine we want to run in French and we’ve defined the language code for French to be “fr”:

s %session.Data(“ewd_Language”)=”fr” or d setSessionValue^%zewdAPI(“ewd_Language”,”fr”,”csp:”)

You only need to do this once. The value will automatically persist throughout the session.

• If translations exist, they will now be automatically displayed to the user. If you want to make changes to the CSP application, you should use and modify the .ewd Design Page copies and recompile them. Any text changes will be automatically identified and assigned new text ids, as if it was a standard eXtc Web Developer application. Text that is created within any of the scripts or back-end Caché logic within your CSP application will not, of course, be translated. However, if you wrapper any text using the errorMessage() or systemMessage() functions, then the text will be integrated automatically into the translation mechanism. Simply specify a sessid value of “csp:”, for example:

s error=$$errorMessage^%zewdAPI(“This is an error message”,”csp:”) s warning=$$systemMessage^%zewdAPI(“This is a warning”,”warning”,”csp:”)

If you identify and wrapper all the text in your scripts, then your entire CSP application will now run in multi-lingual mode.

Documents

eXtc Web Developer - M/Gatewaygradvs1.mgateway.com/download/multiLingual.pdfeXtc Web Developer’s Solution eXtc Web Developer removes all these problems and provides a very simple