Crowd-Source Language Improvement

Introduction to Translated Language Improvement

Caliach Vision, although written in English, is available in translated Language Editions. The program, external strings (messages in the main), help and other texts for these editions have been translated by a machine translation service and therefore are not perfect translations.

However, there is a built-in channel through which you can improve translated texts yourself by contributing, via the Internet, to Caliach's master translation database. As improvements are made your copy of Caliach Vision will be automatically updated with everyone's improvement contributions. This process of collective contribution is commonly called crowd-sourcing. It has the advantage over other methods of translation improvement that you, the user of the program, typically has much the best insight into local language terms and expressions than even professional translation services. You do not just benefit from your own contributions but you benefit from all the on-going contributions made by Caliach and other users of your language edition.

The following illustrates the process of user-generated language improvement using standard HTTP posts and gets between any Caliach Vision user connected to the Internet. The black lines in the diagram show crowd-source text change contribution data flow. The red lines indicate the routine copying of database files. The blue lines indicate the subsequent all-user language update data flow (see 8 in the data flow listing below).

Structure of communications between a Caliach Vision user and the www.caliach.com server and between the server and the master/moderator of language translations

The data flow is as follows:

  1. When you open the Crowd-Source Language Improvement window a check is made that you have an active connection to www.caliach.com, and if so the Language list is downloaded to populate the drop-down list.
  2. You can then read master data from the server, having selected the appropriate reference. Any reference can be selected with a minimum of 5 characters, including HLP. and EXT. help and Extra translations, although these are not included in any subsequent automated updates. Your license is then authenticated, any rules enforced and the selected translation master data returned to you.
  3. You can then modify any of the language texts listed with no time restriction in doing so.
  4. You then operate Post Contributions to the Server which uploads and inserts your contribution to the server database.
  5. At any time you can Fetch My Recent Contributions from the Server which will give you confirmation of your contributions and in due time what action the moderator has taken.
  6. In due course a moderator will view your contributions and the actions taken will be posted back to the server database. If your contribution is accepted it will update the master database. Regardless of that your copy of Vision.lbs and Strings.stb will have the changes applied (some, such as menus only reflect the change after re-starting).
  7. Routinely the updated master database will be copied to the server and then you will see your contribution in the latest master translation data.
  8. Any Caliach Vision (including demonstration editions) user with a locale other than en and have the Check for language improvements on startup User Preference set will:
    1. If the user has an Internet connection, a request to the master database is made for any updated texts.
    2. On downloading, Caliach Vision appends any new texts to the local network ProgLang.<locale> file. The first time you use the a newly installed Vision.lbs a single record of the last updated language text will be used to set the last update date and time for future reference.
    3. All Caliach Vision users, on startup, check the appropriate data folder datafile ProgLang.<locale> file to see if language texts need updating, and if so updates them automatically without user intervention. This applies to Vision.lbs and Strings.stb, but not Help or Extra translations. There is a system option optLangLocalPriority that is set to 1 prevents updates to texts that have File -- Advanced -- Localisation texts created in the Custom/Translate.df1 file.
    4. If sites have multiple locale editions operating, at least one user of each locale will need to have their User Preference set to provide ProgLang files for all installed language editions.

To contribute, operate the File -- Improve the Program Translation menu function and, if you are connected to the Internet, the Crowd-Source Language Improvement window will open.

Language Improvement Window

Crowd-Source Language Improvement

When you open the window there is a slight pause as a session is started with www.caliach.com server and the list of languages are downloaded. If this fails an explanation will be provided and the window will not open.

When opening the window it also builds lists of open objects. By objects we mean Menus, Windows, Reports and Toolbars. And by open we mean that they are currently visible somewhere on the screen. All menus other than context menus are always open. If you are concerned about a text on an operational window, simply have it open before you operate File -- Improve the Program Translation. Reports are a little odd in that to have them available you need to print to Screen or Preview and leave the Screen or Preview window open. Toolbars are embedded in windows and for them to listed the window must be open.

Selecting from the Object Type and Object dropdown lists chooses a Reference for you that identifies the class in the master language database. It will also default the lanuguage list to the language of your language edition. You can change this if you want to contribute to another language.

Pre-opening windows and reports of interest and using the dropdown lists is by far the easiest way of selecting the texts you want to change. But you can also directly type a Reference.

A full Reference is a pointer to a specific individual text somewhere in the program. This identifies where the text came from and where any translation will be applied. For example, the text before the part number field at the top left of the Parts Maintenance window Characteristics tab pane has the English text of Part number. The Reference to it is VISION.wPtmEdit.$objs.Tab.$bobjs.1260.$text where:

  1. VISION = the library VISION (always in upper case)
  2. wPtmEdit = the name of the class in the library (this is case-sensitive)
  3. $objs = the group of objects on the window class
  4. Tab = the name of the object containing the object, in this case the tab pane
  5. $bobjs = the group of background objects in the tab pane
  6. 1260 = the unique identifier for the backgrowd label containing the text
  7. $text = the property of the object that contains the language text

These are then strung together with dots between to make a full Reference. You are unlikely to know exactly what these codes and names are but there is a simple technique for finding out.

Code

How to find

VISION

The library name prefix is always VISION but other libraries such as ADHOC also exist in translated form. To identify the external Strings that are stored in Extras/Strings.stb use the code STR and for Help texts (like you are reading now), use the code HLP. There are also extra tranlation texts, some associated with the Installer, others with the Omnis Studio engine and server messages. These are prefixed with EXT.

Classname

Almost all classes have Help and the help file name is a lower-case version of the classname. You can see that by using the help system (note that the last line of each help file gives the class with upper and lower characters preserved. For example this page shows the class wXlateCrowd.

For Strings it is a little bit different as there is no reference chain to work from. Each string has a unique name. So STR.optBoMZeroQty identifies the description text for the optBoMZeroQty option. Most strings that you will encounter are in Ok, Yes/No and Working messages and these are identified as 4 digit numbers prefixed with a lower-case s, so STR.s4000 is the message text 14000. If you are spotting while working they can be identified by number if you have the Show String Numbers checkbox checked in the File -- Preferences -- Program Message Log window. You can also see all strings in the File -- Advanced -- String Maintenance window.

Help is also different and in the form of HLP.wXlateCrowd.... where the HLP. is followed by the case-sensitive file name (as in the VISION library described above), then followed by a series of numbers that identify sections, paragraphs, etc.. Although very specific they are not really useful to you to identify texts. You need to do this through the base English or translation text shown.

Later full path

This varies depending on the complexity of the object. Note that some objects have several associated texts. Menu lines have a line text ($text) and a help text ($helptext) when tooltips are switched on. Buttons have $text and $tooltip. Lists have $columnnames and $tooltip. You will see them all in the listing you receive from the server.

You don't really need to know the full path, just the begining part is sufficient. When you operate Fetch Master Texts from the Server the server will retun all References that start with your entry. So typing in STR.s400 will return all strings from STR.s4000 to STR.s4009. Don't forget the dot! And the dowloaded list will show all the individual texts and their exact Reference.

Once you have a list of translations you can change any in the list before posting your contributions using the Post Contributions to the Server button.

Now you need to read the Rules to Follow for Contributions section below.

Field

Description

Reference

The object reference for which translations will be identified.

Your name

Please enter your full name so that we know who to associate with the improved translation.

Your email

Please enter your email address so we can contact you if clarification of translations are needed. This will not be used for sales purposes.

Text list

List of texts from the server. Click to select a text and change it below.

Translation

You can modify the tranlated text here.

Mass change everywhere

If you check this, the translation will be changed everywhere the master English text is present in the program.

Base English

The base English text for the object involved.

Your comment

You can add a comment if you want to explain your change.

Button

Action

Fetch Master Texts from the Server

Click to fetch from the server all the master English and translation texts for an object.

Post Contributions to the Server

Click to post a language improvement contribution.

Cancel Changes

Click to cancel any changes you have made.

Fetch My Recent Contributions from the Server

Click to fetch the language improvement contributions you have recently made. This opens the User Contribution to Language Improvement window.

Rules to Follow for Contributions

Rule

Recommendations

Terms

Terms for things can be very specific to a business. For instance, Part number can be a Part code for in some businesses and Item code to others. You should refrain from changing such terms just because you use a different term. If the term is wrongly translated, then fair enough, but where the translation is correct but just not what you traditionally have used in your business then changing it may well upset others.

Consitancy

It is important that terms are consitantly used thoughout the program. It would be confusing to users if Part number, Part code and Item code were all used in different places in the program to identify the same thing. The use of the Mass Change Everywhere checkbox is useful here. But if you use it make sure that you explain the mass change in your comment as the exact text you are wanting to mass change is not likely to be obvious to the moderator, and Mass Change is not automatic. For example, comment something like Change all "Part number" from "Numéro de pièce" to "Numéro de Pièce" in locale fr.

Character Case

In some languages the case of a character is important and where this is relevant maintain the program standard where possible. So, Part number is not the same as part number, and this is also dependant on context. For instance menu lines, buttons and other functions are often capitalised as in Change Part Number....

Punctuation

For languages that use Latin-style punctuatuation, you should preserve this as much as possible. Some texts are joined together in the program so adding extra punctuation can produce an odd result. Sometimes punctuation has a specific meaning. For example ... at the end of a menu line indicates that a window or message will open. Some texts are in fact lists of texts seperated by commas or carriage-return characters. For example, list headings ($columnnames), tab pane titles ($alltabcaptions) and others.

Illegal and Special Characters

Some characters have a special meaning in the program and should be avoided. Square brackets have a special function in Omnis Studio so, unless they are in the English, do not use them. The apostophy and quote characters also have a special meaning within calculated values as they demarcate text. If they are in the English, then they must be preserved for the text to be useable.

Use of the single-quote (apostrophy) character in quoted text is problematic as it is talken as the end-of-text marker. See Square Bracket Notation below.

Placeholders

Many texts contain placeholders which are special character patterns that the program uses to substitute data. So for example a string may say The part number is %1. which in the program will show as The part number is ADH20134.. It is important that these placeholders remain in tact and in the correct place in the text. Looking at the English master text will give you an idea of the placeholders as they are codes rather than words.

HTML Tags in Help

All HTML tags in English master texts muts be preserved in the translation, otherwise formating of help pages is broken and text can be lost.

Square Bracket Notation

Omnis Studio has a clever way of permitting calculations to be made inside text and replacing that with the result of the calculation. This is similar to placeholders but more complex. Such calculations are enclosed in square brackets, for instance [#D] will imbed the current date. You should make sure these are not disturbed from the English master text. There is one exception to this. Some calculations include language text enclosed in single-quote (or apostrophy) characters. These texts can be re-translated. For instance, [pick(#R=0,'Some records listed','No records listed')] can have the Some records Listed and No records listed changed, but nothing else.

If a single-quote (apostrophy) character is needed within quoted text (as in French) you need to double-up. Similarly, with square-bracket characters. So if you want 'I'm great! [ha, ha]' must be entered as 'I''m great! [[ha, ha]]'

Zero Width Space

Some languages like Thai, Korean and Chinese do not segment words with spaces. This is not normally a problem. Particularly in the Help it becomes a problem for word search. If at all possible where texts are long in the Help with these languages you should include the Zero Width Space character so that help word search can break down a sentence into individual words.

Requesting a Block on futher Changes

Sometimes you may wish to block other uses of your language translation from changing it back into something else. This may be for technical reasons. The moderator can do this, so if you want the text blocked request that in English in your comments.

Blocked Texts

If the text you have translated has been blocked for changes in the master database an automatic moderator comment will appear telling you this. Texts that exists but are blocked from translation altogether will only be seen if you select English. And no English texts can be changed.

Abuse

This is a community facility and any abuse will not be tollerated. It relies on trust that the openness of the system will not be abused. Moderators have power and tools to block users who seek to abuse this community facility.

See also: -

Compiled in Program Version 5.04. Help data last modified 28 Jan 2013 08:57. Class wXlateCrowd last modified 18 Feb 2015 01:54:58.