- Introduction to the Language Swap System

The Language Swap System allows you to translate your textual data into as many languages as you wish to support for, output on reports and other output to satisfy a multi-lingual community.

For example, you may want to report your Financial Statements in 2 languages other than your base language in which you work normally. This may be to satisfy outside investors or local tax authorities or regulators. Or you may have many customers that speak another language and want to have their quotation line items in their language.

The system does not translate texts into another language for you automatically. You have to decide what languages you are going to support and what texts you wish to translate. The system provides you with a way of storing your translated texts and then automatically swapping those translated texts for the normal base language texts when requested and appropriate.

The Language Swap system is highly flexible but as ideas, these are circumstances where it can be useful:

How Language Swap Works

The Language Swap system works by maintaining a separate database of text translations. These translated texts are linked to key field values in your data, such as specific part numbers, to a particular language and to a particular field of data. Only character type data can be translated and then only from fields that are free-entry and not associated with codes, relationships, or other fields that would corrupt the logical integrity of the system.

The database of Swap Language translated texts is maintained outside your normal datafile in the same way as the optional Keyword and Linked Files databases are. If you choose to switch the Language Swap system on, you will create or open a datafile with the same name as your main datafile with the file suffix .LSW rather than .DF1 (typically they are in lower-case). This file exclusively contains the text translation single file ALTFILE, in many ways similar to the Keyword system datafile.

You can control the translation languages and the extent to which translations are available in the Language Swap system.

It is very simple to get the Language Swap System operational. These are the steps:

  1. Open the Company Details Maintenance window using File -- System Manager -- Company Details menu path.
  2. Select the Localisation tab pane.
  3. Make sure that the Base language code and name fields are correct. Languages are represented by two lower-case characters and we recommend that you use the ISO 639-1 standard (http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) as you will then be consistent with external translators such as Google Translate. For example, for English enter en and English.
  4. You then enter your swap languages as code and name pairs separated by a comma in the Language Swap languages field. You separate each language pair with a semicolon. So, for example, if you want French, Thai and Korean you would type fr,French;th,Thai;ko,Korean. The order you place them in the field will determine the order they will be listed in any Swap Language lists. Do not include your base language.
  5. With at least one swap language pair entered, the Language Swap database will be opened or created for the first time, and a Language Swap list of your languages will appear on the main toolbar just ahead of the Report Destination list for printing.

The following illustrates the key visual parts if the Language Swap system:

Language Swap Setup illustration.

Tip TIP: You can prevent Users or Groups of users from using the Language Swap System using the system option optLangSwapBlockUsers. Language Swap blocked users and groups. Language code=User,Group list;... list of languages and users or groups blocked from using them. Applies also to Administrators. If no language code is set block applies to all languages. e.g. fr=AA,GM;th=AA,Sales. The block on language use for a user does not stop the Language Swap system functioning. It only means that the User cannot select a swap language in the toolbar list. Indeed if the user is blocked from all languages the Language Swap list will not be present in the toolbar. However, Language Swap is still active and will translate automatically when Customers, Suppliers or Marketing records have a language set for them.

Note NOTE: Changing the languages after you have created translations will not effect any data. Changing the order will simply change the listing order. A language is only valid if both the code and name are entered. Removing a language will not delete any translated texts you have created in the past - they simply will not be used because you will not be able to select the language in the toolbar list. However, you also will not be able to add any new translations for a missing language.

Language Swapping

In the Language Swap list in the toolbar, selecting your local base language turns off any text swapping. Choosing a non-base language will lead to the Language Swap system becoming active in replacing your standard texts with text translations you have made, where available, in the language you have chosen in the toolbar list.

Example of Language Swap balance sheet in Korean

Essentially language text swaps take place in two places:

Besides the Language code settings in Company Details Maintenance, you can set a language code for Marketing Records, Customers and Suppliers. If the language code in these matches a Swap Language code in your settings the following behaviour will exploit translations you have made:

Data

Activity

Marketing

The following activities are affected by the Marketing record language setting:

  • Letter References and Texts will be translated into the language of the Marketing record when letters are printed or emailed. When you select a standard letter it will be language swapped for you and you can modify it's language text. If there is no specific language set, then the Language Swap toolbar choice will apply. Also the Address, Contact and Country will be translated if appropriate.
  • When Customers or Suppliers are created from Marketing records they inherit the language setting.

Customers

The following activities are affected by the Customer language setting:

  • Letter References and Texts will be translated into the language of the Customers when letters are printed or emailed. When you select a standard letter it will be language swapped for you and you can modify it's language text. If there is no specific language set, then the Language Swap toolbar choice will apply. Also the Address, Contact and Country will be translated if appropriate.
  • When creating Customer Parts data from parts will be translated where available for the Customer's language, or the Swap Language if the customer language is blank.
  • Texts translated to the Customer language will be transferred to a Quotation, Sales Order, Estimate, Job and Invoice. This is regardless of the Language Swap setting in the toolbar if the Customer has a Language set. If it is not then when the document is created the Language Swap language will apply.
  • On the whole, customer reports translate to the Customer's language. If the customer's language is not set, then the Language Swap will apply.

Suppliers

The following activities are affected by the Supplier language setting:

  • Letter References and Texts will be translated into the language of the Supplier when letters are printed or emailed. When you select a standard letter it will be language swapped for you and you can modify it's language text. If there is no specific language set, then the Language Swap toolbar choice will apply. Also the Address, Contact and Country will be translated if appropriate.
  • When creating Purchase Parts data from parts will be translated where available for the Supplier's language, or the Swap Language if the supplier language is blank.
  • Texts translated to the Supplier language will be transferred to a RFQ or Purchase Order. This is regardless of the Language Swap setting in the toolbar if the Supplier has a Language set. If it is not then when the document is created the Language Swap language will apply.
  • On the whole, supplier reports translate to the Supplier's language. If the supplier's language is not set, then the Language Swap will apply.

Note NOTE: Contacts and Addresses

In general it is not particularly useful to translate Addresses and Contacts as your postal/delivery system is unlikely to read a foreign language. But there are circumstances where some data could be usefully swapped into another language. The following rules apply to Language Swap of Contact, Address (and Country) texts:

  • When printing Standard Letters, Envelopes and Labels the Marketing, Customer or Supplier language will apply if there is one. If not, the selected Language Swap language will apply
  • When addresses are shown on windows they are never language swapped.
  • When documents with addresses are printed the Customer or Supplier language will apply. If no language is set the Language Swap selection will apply.

What Can Be Translated?

Only certain files can usefully have texts translated in Language Swap. Typically on Data Maintenance windows where you see this icon Swap Language Translation icon you will be able to click on it to maintain Swap Language translations. This opens either the Language Swap Maintenance by Record window or the Language Swap Maintenance by File window depending on the context. The menu function ScratchPads -- Translate for Language Swap operates in the same way on the current top window. To restrict user or group use of these window icon buttons set the privileges for these two menu functions: File -- Advanced -- Language Swap Maintenance by File and ScratchPads -- Translate for Language Swap respectively. The best way to find out what files and fields can be translated is to view the dropdown lists in Language Swap Maintenance by File.

The basic rule is that data texts can be translated that are useful for a one-time translation. There is no point in translating inventory comments, for example, as they are too numerous and of little value outside the business.

It is also important to understand that the Language Swap system enables the translation of data not the program, and things like report literals are part of the program. So, in the example of the Korean translated balance sheet shown above, the top headings are all in the program language of English. An installation of Caliach Vision can, of course, be translated into another language other than English using the Language Management feature, but this is a major undertaking given the size of the program. A better solution to compliment the use of the Language Swap feature is to customise the commonly used report classes, translate the literals on them and have the user select, for example, the Korean Balance Sheet. Then the entire document, rather than just the data is in the foreign language.

In summary, the following table lists the uses of translations of various data:

Data

Use of Language Swap

Addresses and Contacts

Standard marketing letters and addresses on documents, such as quotations, sales orders, estimates and jobs, purchase orders, returns, invoices and credits, etc.. As a special case with customers, the address Default dispatch and packing details is translated when passed to a SO or Job.

Bills of Materials

BoM reports and WOs, Picking Lists and PO Outwork listings.

Company Details

Typically translated texts are applied to documents. Specifically the default payment terms when applied is translated onto the Quotation, SO, Estimate, Job or Invoice. Financial Statement titles are useful to translate if Financial Statements are to be Language Swapped.

Countries

Countries listing report and as Addresses and Contacts above.

Currencies

In documents such as PO, SO, Jobs and Invoices the currency title is translated to the currency of the supplier or customer, or if they do not have one set, the Language Swap at the time of printing.

Currency listing report is subject to Language Swap.

Customer Parts

If the customer has a language set, or the Language Swap is set, the description of a newly created Customer Part record will be translated from the part texts. This allows you to have SO or Job line item descriptions for a specific customer part to be held in it's appropriate language. Customer Parts can also be local text with translations made so that when they are applied on a SO or Job depending on the customer language or Language Swap that is set at the time. Because of the dual mechanism that can apply, you should avoid doubling up by making translations of records that are already pre-translated in the base language data.

Customer Parts reports will Language Swap.

Customers

In general where a customer has a specific language set, then translations will be made to that language. Otherwise translations will be made according to the Language Swap set in the toolbar.

When Customer Parts are created the part description will translated to form the customer part description. When data is added to a Quotation, SO, Estimate, Job or Invoice, the text data will be translated onto the document data. When customer reports are printed and any document printed, translations will be applied. Letters, Emails and reports will be translated. A translated form of the User fields will be passed to the document data when options permit.

Delivery Details

Delivery detail Language Swap will apply on RFQ and POs as well as delivery detail reports.

Email Texts

Marketing, customer, supplier or Language Swap will apply to Email subject and body texts.

Employees

Language Swap translations will apply to employee and work history reports.

Engineering Data

Customer, supplier or Language Swap translations will apply to engineering reports and when engineering data is linked to documents.

General Ledger

G/L reference and descriptions are subject to language swap in Financial Statements and G/L reports complementing General Ledger Report Headings.

General Ledger Assets

Asset Register reports.

General Ledger Report Headings

Report heading texts are subject to Language Swap in Financial Statements and reports.

Index Codes

Index descriptions are generally translated into an appropriate language context.

Letters

Standard Marketing letters are translated according to the context of their use.

Warning WARNING: Do not translate special syntax such as <B>, <I> or <U> or square bracket notation or style escape strings. These should all remain intact in your translations.

Marketing records

In general where a marketing record has a specific language set, then translations will be made to that language. Otherwise translations will be made according to the Language Swap set in the toolbar.

Customers or suppliers are created from Marketing records the language will migrate to the new customer or supplier. Letters, Emails and reports will be translated. Marketing reports will show translated text.

Non-Conformance Reports

Language Swap applies to NCRs when reported.

Parts

Language swap applies in parts reports. When parts are used on documents an appropriate context translation will be made to part texts. This particularly applied to Customer and Purchase Parts data descriptions or any document line items when a language applies. User field translations will be passed to WO's when options apply and Language Swap is active.

Warning WARNING: Where individual texts contain a Engineering Text link code at the start for embedding in documents, you should leave this out in your translations. The link will be established before any Language Swap takes place and so leaving it in your translation will mean it will be printed on the document.

Process Route Operations

Language Swap translated for reports. When they are replicated for a WO and the WO is Language Swapped when printed, the original operation texts are re-translated from the process route, so in this case modifying WO operation texts for the WO will not be useful for the translated version.

Purchase Parts

Purchase parts typically derive a description that is a supplier or Language Swap translation of the part description. Alternatively, the description can be translated if Language Swap is set when creating a RFQ or PO. The document line item descriptions are stored in a translated form.

Quality Report and Certificate

The quality comment can be translated in context.

Standard Texts

Standard purchase, sales, works and engineering texts translations will be made in context on documents and reports.

Suppliers

In general where a supplier has a specific language set, then translations will be made to that language. Otherwise translations will be made according to the Language Swap set in the toolbar.

When Purchase Parts are created the part description will translated to form the purchase part description. When data is added to a RFQ or PO, the text data will be translated onto the document data. When supplier reports are printed and any document printed, translations will be applied. Letters, Emails and reports will be translated. A translated form of the User fields will be passed to the document data when options permit.

Work Centres

Work Centre descriptions will be translated in context, in particular on Work Orders and Jobs.

Customisation Customisation and Custom Reports

ScratchPads and Workflow Triggers and Alerts

You can use the Language Swap System to display language translations directly on the ScratchPads and Workflow Triggers and Alerts or, for that matter any custom report. To do this you use a function $ctask.tLangSwap.$GetSwapText (pKeyValue, pColName, pLanguage, pNormalText). The four parameters are pKeyValue which is the identifier of the record and needs to be prfixed with pRow., for example pRow.PTMPTNO for parts or pRow.CUSCODE for customer. Then the Column Name of the field in the record you want translated. Then optionally the language code for the translation. If this is not entered explicitly the Language Swap toolbar choice of language is applied. Finally, again optionally, the nomal, or un-translated text. If there is no translation available, this text will be returned.

For example, a calculated Parts ScratchPad field calculation could be

$ctask.tLangSwap.$GetSwapText(pRow.PTMPTNO,'PTMDESC','ko',pRow.PTMDESC)

would list all Korean translations of the part description in a column in the Parts ScratchPad. Note the pColName needs to be a quoted string. Using (pRow.PTMPTNO,'PTMDESC') would apply the Language Swap toolbar choice for the column at the time the part was added to the ScratchPad.

As another example you could add a column to the General Ledger ScratchPad to show a translated account description. The calculation code would be:

$ctask.tLangSwap.$GetSwapText(pRow.GLACODE,'GLADESC','fr')

ScratchPad translation example

Reports

Reports that were derived from pre-V4 designs will not support Language Swap without functions being added. The easiest way to achieve this is to add to the Record $print method:

Do $ctask.tLangSwap.$LoadSwapInFiles (pDataRow, pFiles, pLanguage)
Do default

pDataRow is either a row variable or a list variable with the current line set. pFile is a quoted string of any number of tables, comma seperated.

For reports to support Language Swap they need to be tailored with code that implements the swap process. Various functions are available to implement this.

Method (parameters)

Function

$ctask.tLangSwap.$LoadSwapInCRB (pLanguage, pDataRow)

Replaces any fields in the current main file in pDataRow to their swap translation or to pLanguage if not blank.
 
This is typically called from the $printrecord class method of a report which contains the code:
 
Do $ctask.tLangSwap.$LoadSwapInCRB('', iDataRow)
Do default

$ctask.tLangSwap.$LoadSwapInFiles (pDataRow, pFiles, pLanguage)

Replaces any fields in the pFile table columns in pDataRow to their swap translation or to pLanguage if not blank. pFiles can contain any number of table names separated by commas. pDataRow can be a row variable or list with the current line set. For example, this line of code could be used to language swap G/L financil statement report:
 
For iDataList.$line from 1 to iDataList.$linecount step 1
  Do $ctask.tLangSwap.$LoadSwapInFiles(iDataList, 'GLAFILE,RBPFILE')
  Do $cinst.$printrecord()
End For

$ctask.tLangSwap.$LoadSwapInList (pList, pFiles, pLanguage)

Swaps translated texts for the Swap Language, or to pLanguage if not blank, for columns in the list pList for columns in pFile tables. pFiles can contain any number of file names separated by commas. The list must contain columns for the tables's key columns.
 
For example in an appropriate method in a report where a list of data is passed the following line of code will make the report Swap Language aware:
 
$ctask.tLangSwap..$LoadSwapInList(iList, 'GLAFILE,RBPFILE')
 
iList is the list variable containing the data, and should not be of type field reference otherwise the source list will change which may lead to undesirable consequences. In this case the list contains columns from both the GLAFILE and RBPFILE.

$ctask.tLangSwap.$LoadSwapInRow (pRow, pFiles, pLanguage)

Swaps translated texts for the Swap Language, or to pLanguage if not blank, for columns in the row pRow for columns in pFile tables. pFiles can contain any number of table names separated by commas. The row must contain columns for the table's key columns.
 
For example in an appropriate method in a report where a row of data is passed the following line of code will make the report Swap Language aware:
 
$ctask.tLangSwap.$LoadSwapInRow(pList, 'CUSFILE', CUSLANG)
 
iRow is the row variable containing the data, and should not be of type field reference otherwise the source list will change which may lead to undesirable consequences. In this case the row contains fields from both the CUSFILE and translates into the customer language, if set, otherwise the Swap language.

$ctask.tLangSwap.$LoadSwapInWOO (pDataRow, pLanguage)

Special for WOOFILE records in WOs to replace pDataRow columns with PROFILE translations. WKOPTNO and WOOOPNO must be columns in pDataRow. It translates WO operations with Process Route text translations.

$ctask.tLangSwap.$lookupIDX (pCode, pLanguage)

Returns a language swap text for an index code description in a similar way to the standard lookup would do. pLanguage will overwrite the current swap language. pCode must be the full IDXID value, for example:
 
Calculate iDescr as $ctask.tLangSwap.$LookupIDX(con('3', iRow.PTMP1CD), 'fr')

$ctask.tLangSwap.$lookupTXT (pCode, pLanguage)

Returns a language swap text for an standard text in a similar way to the standard lookup would do. pLanguage will overwrite the current swap language. pCode must be the full TXTCODE value, for example:
 
Calculate iText as $ctask.tLangSwap.$LookupTXT(con('S', iRow.PTMTXS), 'de')

MEMORY.m_McdAltRow. <fieldname>

This syntax should be used only for Company Details (from the MCDFILE table) on reports where Language Swap is needed for appropriate columns. For example, in a report showing the text title for Default Sales Order Payment Terms you would usually use MEMORY.m_McdRow.MCDTERM in the report field dataname. If you want Language Swap to apply to the field use MEMORY.m_McdAltRow.MCDTERM instead.

$ctask.tLangSwap.$mcd (pColumn, pLanguage)

Returns the language translations of MCDFILE pColumn but unlike the MEMORY.m_McdAltRow syntax above, you can force a language with pLanguage.

$ctask.tLangSwap.$GetSwapText (pKeyValue, pColName, pLanguage, pNormalText)

Returns the language swap text for the pColName column for the row keyed by pKeyValue. If there is no language swap it returns the pNormalText text. Should be used in custom ScratchPad columns or Workgroup Alert or Trigger calculations where language swap is called for. For example:

 
$ctask.tLangSwap.$GetSwapText(pRow.GLACODE,'GLADESC','fr')

See also: -

Compiled in Program Version 5.04. Help data last modified 23 Jan 2017 05:36. No class.