.CONVERT TRANSLATE

This subroutine converts a string from one language to another using the Application and System Dictionaries.

Usage:

      PASS         <trans_text>               FIELD            SHARE? Y
      PASS         <trans_error>              FIELD            SHARE? Y
      PASS         <source_text>              FIELD            SHARE? N
      PASS         <from_lang>                FIELD            SHARE? N
      PASS         <to_lang>                  FIELD            SHARE? N
      PASS         <trans_type>               FIELD            SHARE? N
      PASS         <trans_app_id>             FIELD            SHARE? N
      PASS         <trans_ver_id>             FIELD            SHARE? N
      PASS         <field_name>               FIELD            SHARE? N
      SET      --- .CONVERT TRANSLATE         =
      SUBR     --- .CONVERT TRANSLATE               DETACHED     END? N  FAIL 0
      *        Check for errors
      IF       --- .CONVERT TRANSLATE         NE

Description:

This subroutine converts a string from one language to another using the Application and System Dictionaries. The first five parameters are required, if any are missing the subroutine will CANCEL. The <trans_type>, <trans_app_id> and <trans_ver_id> parameters are optional. The translation uses the Dictionaries and Translations you have entered in the applications. Note that this routine should be invoked via SUBR with a RELATED or DETACHED invocation to ensure none of your fields are changed.

<trans_text> returns the translated version of <source_text> (Required). This must be PASSed with Share "Y" to return the value.

<trans_error> returns any addiitonal error messages from the translation (Required). This must be PASSed with Share "Y" to return the value.

<source_text> is the text you want translated (Required).

<from_lang> is the language ID that identifies <source_text> (Required). This must be a valid language code as defined in Appx System Administration.

<to_lang> is the languge Id you want <source_text> translated to (Required). This must be a valid language code as defined in Appx System Administration.

<trans_type> is the type of translation desired (Optional). Must be one of Field, Token, Clause, Message or Text. Defaults to Field if not PASSed, or is blank.

<trans_app_id> is the Application Id whose dictionaries should be used for the translation (Possibly optional, see NOTE below). Defaults to the current application if not PASSed, or is blank.

<trans_ver_id> is the Version Id whose dictionaries should be used for the translation (Possibly optional, see NOTE below). Defaults to the current version if not PASSed, or is blank.

<field_name> (Version 6.0 & higher only) is only required for Token translation types. It is the name of Token field you are translating. This is only available in Release 6.0 & higher. Prior to release 6.0 it is not possible to use this API to translate a Token field.

If <trans_text> is too small to contain the translated text, --- .CONVERT TRANSLATE will contain 'Data was truncated'.

In all cases, if a translation is not found in the Application Dictionary, then the System Dictionary will be checked. If a translation is still not found, the text will be added to the Application Dictionary.

Note that this routine will return the <source_text> in the <trans_text> field if it is unable to translate <source_text>. In other words, you will always get something back from this routine, either the translated text, or as best a translation as possible. This is especially true if you are using the 'Text' <trans_type>. The translation routine always starts with the largest block of text and works it's way down until it has attempted everything. If it can find a match for the entire block of text, it will return that. If not, it will then look for matches of the paragraphs in the text. If it can find a match for the paragraph, it will return that. If not, it will look for matches at the sentence level. If it still cannot find a match, it will attempt to translate individual words, depending on the "Translate Words" setting on the <from_lang> file. Thus the result returned could be a mix of the original text and the portions that were able to be translated.

NOTE: If you invoke this via a SUBR command, the <trans_app_id> and <trans_ver_id> are NOT optional and must be PASSed for the correct dictionaries to be referenced. If you invoke this via a GOSUB, then <trans_app_id> and <trans_ver_id> are optional, however, --- TEMP 2k and some numeric PDFs (--- AI, etc) are not preserved by the subroutine and will change.

Comments:

Read what other users have said about this page or add your own comments.

It appears that the fields <trans_app_id> and <trans_ver_id> are indeed required, as it doesn't always seem to default properly to the currently running application/version.

-- AlKalter - 2014-10-01

-- JeanNeron - 2012-02-04