support: Customer Portal
Focused on delivering choice, investment protection and flexibility to organizations with valuable COBOL assets

Veryant Knowledge Base
Home > All Categories > isCOBOL General > Localization > How do I use text that has been translated into other languages in my screens and messages?
Question Title How do I use text that has been translated into other languages in my screens and messages?

How can I display Chinese, Japanese or other double-byte characters in my user interface? 
How do I specify Unicode characters in a language resource file?
What file format do I need to get from the translator?
What word processors or editors do I need to use?


The isCOBOL APS language resource feature provides an easy way to localize your application to multiple locales and to configure the text for your user interface at runtime from among different languages.

During the initial program initialization and optionally before calling a subprogram, the isCOBOL Runtime Framework loads a specified language resource file. This file is a Java properties file which contains any number of name=value pairs. You specify where in your program you want these resource values to be used with a letter R followed by the quoted name of the resource. For example,

DISPLAY R"Greeting". 

will use a resource named Greeting that has been loaded from the language resource file. If your resource file contains the following:

Greeting=Hello World 

Then the program will display:

Hello World 

A resource name can be used anywhere in your source code where it is valid to use a string literal.

Follow these steps to create a multilanguage version of your program:
  1. Search for string literals in your program source code
  2. Copy each string literal to a text file and remove the quotes
  3. Add a resource name followed by an equal sign to the beginning of the line in the text file
  4. Replace the original string literal in the source code with the letter R (or lowercase r) followed by the quoted resource name
For example, you could replace "Please enter a valid credit card number" with r"ValidCCNumberMsg" and then add the following line to the resource file:

ValidCCNumberMsg=Please enter a valid credit card number 

To assist the translator you can add a comment line before or after each text resource value and describe the usage and/or context. For example,

# Context: Message displayed on line 24 when user has entered an invalid credit card number
ValidCCNumberMsg=Please enter a valid credit card number 

The name of the language resource file is constructed from the values of the following framework properties:


as follows (square brackets enclose optional elements): 


For example, if iscobol.resource.file=RES and iscobol.resource.language=en then the isCOBOL Runtime Framework will attempt to load a file named

The resource file must be located in a directory or jar file listed in the class path.

The above framework properties can be set programmatically using SET ENVIRONMENT leaving off the "iscobol." prefix.

An example program which demonstrates this feature is provided in the isCOBOL/sample/multilanguage directory.

While reading property files Java uses the ISO 8859-1 encoding, so the resource files must be written with this encoding. To insert characters that cannot be represented by the ISO encoding, Unicode escape sequences must be used. The escape sequence is composed by \u followed by the utf-16 representation of the character (the same you would use with nx syntax in the cobol source).

You can use the native2ascii utility, which is included with the JDK, to convert localized text files into ISO 8859-1 compliant Unicode escape sequences. The documentation for native2ascii is at:

To translate your resource file into another language, you can use any word processor or editor that can accomplish the job. Save the file as a text file using whatever encoding is convenient. Then run native2ascii to convert the text file to a Java properties file in the correct format (i.e. ISO 8859-1). The native2ascii utility supports all of the commonly used encodings.

The supported encodings are listed at: 

You might find Google Translate to be a useful tool during development and testing: 

For example, at, type the following into the entry-field:

Type username
Type password
Invalid username/password, login failed

Then press the Translate button 
Copy the Chinese values from the Translation field into Wordpad 
Save the Wordpad document as "Unicode Text Document" named chinese.txt 
Execute the following command from the directory containing chinese.txt:

native2ascii -encoding utf16 chinese.txt 

This produces the following output:


Copy these entries into a resource property file as follows:


Alternatively, you can copy the text into Microsoft Word. Then save the Word document as a Plain text file. Then in the file conversion dialog box, select "Other encoding", select "Unicode (Big-Endian)" and press OK. 

As mentioned earlier, you can use other encodings. For example, if you have a text file in Big5 encoding (i.e. Traditional Chinese) then you can convert it using "native2ascii -encoding Big5"
Authored by: Veryant Support This question has been viewed 9287 times so far.
Click Here to View all the questions in Localization category.
File Attachments File Attachments
There are no attachment file(s) related to this question.
How helpful was this article to you?
User Comments User Comments Add Comment
There are no user comments for this question. Be the first to post a comment. Click Here
Related Questions Related Questions
  1. Is there a way to localize (translate) text messages similar to the ACUCOBOL-GT TEXT configuration variable?
Article Information Additional Information
Article Number: 4
Created: 2009-08-28 12:13 PM
Rating: 2 Stars
Article Options Article Options
Print Question Print this Question
Email Question Email Question to Friend
Export to Adobe PDF Export to PDF File
Export to MS Word Export to MS Word
Bookmark Article
Subscribe to Article Subscribe to Article
Search Knowledge Base Search Knowledge Base


© Veryant - All Rights Reserved
Veryant and isCOBOL are trademarks or registered marks of Veryant in the United States and other countries. All other marks are the property of their respective owners.