Programming Multi-Language Studies

Questions and/or Response Text may be displayed in one of many languages.  Survox supports up to 500 different languages including right-to-left languages like Arabic.  You may specify and use more than one language in the same questionnaire but we recommend limiting it to up to 10 languages for manageability.

Multi-Language Studies can be set up and run using the Survox Console but all of the Best Practices below apply. (See Survox Console – Multiple Language Studies for more information)

Encoding/Character Sets

Encodings are a set of characters for which there is a 1:1 correspondence between each character and a number or set of numbers.  These numbers are called code points.  Examples of character sets are UTF8 or Extended_ASCII.  Studies with UTF8 encoding can support all languages within one spec file.

NOTE: Our recommendation is to use UTF8 for all languages, where possible, since it’s the Universal character set and is supported by Survent.    The study server must also be configured to use the UTF8 message file if you are using UTF8 encoding.

Saving from Non-Text Formats

Translations in MS Word format must be saved to text format so that it can be read by a text editor like Ultra-Edit.

The “save as” Word menu should present a list of possible encodings to choose from.  We recommend to always save as UTF8 encoding.   When saving in UTF8 format, there is no need to change the font in the text editor.  You can then use this text file as your QPX and build the syntax around it or do a copy/paste from the saved text file to the QPX (being careful not to break any ideograms).  Alternatively, you could choose to use external language files and use the saved text file as one of the external language files.

NOTE1: When saving from a text editor, we recommend to always save as UTF8 encoding with NO BOM.   If you save with BOM, it can cause issues with your QPX.

NOTE2: Be very careful if you are cutting/pasting into a text file.  This also can cause issues with the encoding of your translated languages and the words may not present properly in the browser.  We do NOT recommend cutting/pasting.

Saving from an Excel document is similar to saving from a Word doc, although it can be slightly more convoluted.  Let’s assume you have a Japanese Excel document.  Excel does not present a list of encodings for text files when you want to use “save as”, so you choose Unicode text when saving, producing a Unicode tab delimited text file (no specification of actual encoding).  If you open this file in Word, you can “save as” choosing UTF8 encoding.

Organization Methods

There are various ways to program languages using Survent. The first thing you need to do is decide how to manage the languages.

  1. If you have separate sample files and quotas for each language, you should build a separate study for each language.
    1. This is the easiest method because the languages are typed in like English for the text and responses.
    2. This is not our recommended approach since you will need to manage separate TR, phone, and quota files.
  2. If you have mixed sample and quotas, but will know the language of the respondent you are calling, you can write separate questionnaires that all use the same sample files and quota files.
    1. This is also quite simple.
    2. By using the QFF_FILENAME= in your study header, all questionnaires can use the same TR, phone file and quota file.
    3. This is one of our recommended approach for this type of method.
  3. If you need to “combine” languages such that you can switch from one to another at any time in the questionnaire, you will need to program all the languages into one questionnaire.
    1. This requires entering all the text for all languages into each question.
    2. There are two ways to do this:
      1. Use the language switches
        1. This is our recommended approach if you only have a few languages. (See below for more information)
      2. Use Include Files (& ampersand files) to call in the translated language text and response for each question.
        1. This is our recommended approach if you have a lot of languages. (See below for more information)

Study Header

The languages that will be used in your spec file must be specified in the study header using the Language= keyword.

The syntax for the LANGUAGE header keyword is:

LANGUAGE=(SET=(<langcode1, langcode2, langcoden>)
DEFAULT_LANGUAGE=<langcode> or **



  Language Keyword Options


This option specifies the two-character codes for each language, and is required for all multilanguage studies. Survent allows you to convert from a two-character code to a one-character code for ease of programming.  Valid languages must be present at the top of the Survox msgfile.



In the above example, English, French, and Spanish are the languages specified for the study using a two-character code.  You would specify each language using \L<2-character code> to switch to that language.



In the above example, you are setting a one-character code for each language.  The first letter is the letter that you will use when specifying the language and the second is the Survox code for that language.  You would specify each language using \L<single code> to switch to that language.


This option selects the encoding for the languages you are using.  The default is UTF8 or extended_ascii and only one character set can be assigned.




The speaking option is the default language from the SET values. If no SPEAKING language is specified, the first two letter code on the list will be used.




Default language is used in the event that a language flag is not specified for survey content.  If not set, this will default to the first language code on the list but you can change it at any time.  This would be the language used if you didn’t specify \L on some text.

When set to “**”, all unflagged content will be displayed for all languages.



In the RESPONSE LIST areas, each new response code starts in the “Default Language” until you specify a \Lxx command or have a [\L=xx] response block.  The same rules apply for \Lxx in the response list as for the text part of the question.


\LEN What is your name? \LFRComment vous appelez-vous? \LSPComo se llama?

In the above example, interviewers will always see INTERVIEWER: PLEASE ASK and then depending on the language mode, they will see one of the three languages in which they should ask the question.


This option makes sure all languages are specified on each question that has any language specified.  The default is not to check.

“\L**” accounts for all languages, unless there are other \L in the text, in which case there must be one for each language in the “set=”.



{ Q1:
\L**This is fine.

{ Q2:
\L**And so is this.\LENEnglish \LFRFrench \LSPSpanish.

{ Q3:
\L**But not this. \LENEnglish.

Response Code Lists

There are two ways to specify languages on response code lists. For example, with question text, you may use “\Lxx” to change to language xx on any particular code in the list. However, if you have many languages or many codes, or you wish to send the entire list to a translator, it is easier to keep all the codes together for each language. Here is an example of both.


\L**Question Text
1 \LEN English text \LFR French text \LSP Spanish text
2 \LEN English text \LFR French text \LSP Spanish text }


\L**Question Text
1 English text
2 English text
1 French text
2 French text
1 Spanish text
2 Spanish text }

Although the first way contains less text, it is more difficult to deal with when translating because you have to copy and paste each line to its proper position on the response list. Using the second way, you can send the response lists out to separate translators and just insert the response list for each language (or use Include Files to read it – See below for more information) into the appropriate place on the list.

Changing the Language

There are two ways to change the language being used.

In the questionnaire, you specify “\L<language code> text” to start a section for a particular language.  You may switch back and forth between languages at any time on a question.

Interactively, if {!ALLOW_LANGUAGE_CHANGE} is set (or the interviewer is interviewing in “debug” mode), interviewers may switch between languages by entering “L=xx” (where xx is the language code) at any question prompt. (See Compiler Commands for more information).

Programmatically, you can use the {!SYSTEM,SET_LANGUAGE,<language code>} statement in the questionnaire to switch the language in effect.  (See System Statements for more information).  By using this, a respondent can choose the language that they want to use.  The language stays in effect until changed again or until the end of the current interview.



Which language would you like to use?
1 English
2 French
3 Spanish }




Whichever language is chosen in the QLANGUAGE question, is the language that will be used throughout the rest of the survey unless it’s changed.

You can record the language currently in use by using the SPECIAL,STUDY_INFORMATION statement, position 110.2.  (See Special Information Statements for more information).



  webCATI Studies

In webCATI, the templates can be created to allow an interviewer to change languages within the SPECIAL block at any point in the study.  Set up a special block that sets the language and control access to it with a button in the buttons.tmpl.

In the buttons.tmpl the following line will need to be present:

<input type=”submit” name=”Special.x” value=”Switch Language”>

The “Value” can be any text that you want to display on the button.

This line should already be in the buttons.tmpl with an >IFDEF wrapped around it.  Using the {!ALLOW_SPECIAL} command in your questionnaire will display the button for use.

The following is a short example of a SPECIAL block:


\L**Set the Language 
1 \L**English
2 \L**Italian }




Once the new language is selected and the !SYSTEM,SET_LANGUAGE has been executed, the templates will display the content for the appropriate language.  The templates must use the >IF @LANGUAGE syntax to control their content based on the language selected.  Information on templates can be found below.

 “Include” file references

Typically, when writing multi-language questionnaires, the text is sent out to be translated in a file and a duplicate file is returned with the translated text. There is a way that you may reference translation documents for all your text instead of having to cut-and-paste the text into each language questionnaire. This can be used for any language script, but it is probably more trouble than help if you only have a few languages but if you have a lot of languages, this is our recommended approach. The more languages, the more savings.

You can send the same template out to be translated, and then reference the translated text across languages. Once this is set up, you can modify the original language documents and the changes will be included the next time you compile the script.

By maintaining separate documents for each language and employing the use of “include file” references, the programming of the spec can occur simultaneously or before the translation of the survey. More importantly, editing can be done to the documents without touching the questionnaire.

The syntax to reference a region of an include file is:

&<filename> (‘start/’end)

The ampersand must be the first character of a new line. Markers within the single parenthesis point to the beginning and end of a section of text in the include file.


Please indicate which main business unit you primarily work with:
1 Automobile manufacturer 1
2 Automobile manufacturer 2
3 Automobile manufacturer 3
4 Automobile manufacturer 4
5 Automobile manufacturer 5  }

In the example above, “Please indicate…..” and responses 1-5 are separate entries for the include file and would look like this:

Please indicate which main business unit you primarily work with:
Automobile manufacturer 1
Automobile manufacturer 2
Automobile manufacturer 3
Automobile manufacturer 4
Automobile manufacturer 5

SCR1 is the reference for the beginning of the question text in the include file, SCRR1 is the reference for the end of the question text and the beginning of the response list, and ESCRR1 is the reference for the end of the response list.

The questionnaire spec, if using only the base language’s (English in this example) include file, would look like this:

&incen('scrr1/'escrr1)  }

The “&incen” reference is calling in the Include file for English.  The (‘scr1/’scrr1) is saying pull the information from the label in the include file called SCR1 until you see the label called SCRR1.  The (‘scrr1/’escrr1) is saying pull the information from the label in the include file called SCRR1 until you see the label called ESCRR1.

In the following example the question gets translated into Dutch, French, German, Italian, Chinese and Japanese. This example has the translated files named ‘inc’ followed by their two-letter language code. This code will be shortened later, but the variable QSCREENER now looks like this:

&incit('scrr1/'escrr1)  }

The “&incxx” reference is calling in the Include file for each language.  The (‘scr1/’scrr1) is saying pull the information from the label in the include file called SCR1 until you see the label called SCRR1.  The (‘scrr1/’escrr1) is saying pull the information from the label in the include file called SCRR1 until you see the label called ESCRR1.

And at this point, the repetitive code can be placed inside a “>repeat” structure, where @lang is a define that will call in the correct Include file.

>REPEAT $A=@lang
>REPEAT $A=@lang

The “@Lang” reference above is referred to as a “>DEFINE”.  (See Meta Commands for more information)

NOTE: You need to retain consistency in the sequence of language codes in the >REPEAT and >DEFINE statements. You can define anything that you don’t want to have to retype later (this helps in keeping the code consistent).



Managing the Message File

The msgfile is a central repository for the error messages. Any error message that is changed there will be shared by all the studies and processes in that environment. The msgfile is a binary file, so it cannot be edited directly. We edit a text file called msgfileutf8.raw for UTF8 encoding or msgfile.raw for Extended ASCII encoding instead and then we use the “makemsg” utility that reads the RAW file and builds the appropriate msgfile.  Ask Support for more information.

NOTE1: In Version 8.8.x+ the UTF8 msgfile is installed by default.

NOTE2: The character(s) specified on the LANGUAGE=(SET=()) statement must match those used on the L= command, \L and !SYSTEM,SET_LANGUAGE commands. Otherwise, the command will have no effect or will generate an error.

You may use a language code that is not supported by Survox, but you will not get the Survox-specific program error messages and prompts in that language. You will get the language text you specify in your questionnaire, but Survox error messages will be in English in this case.

The Survox language codes program and error messages that are currently supported are:

  • DE: German
  • DK: Danish
  • EN: English
  • JP: Japanese
  • FR: French
  • IT: Italian
  • KO: Korean
  • PT: Portuguese
  • SP: Spanish
  • SV: Swedish
  • ZH: Chinese

You can add messages to the Survox message file for your particular language for various program prompts and error messages using the MAKEMSG program.  Ask Support for more information.

Custom Error Messages

You may specifically control the text of the Survox messages for a particular questionnaire or question using the {!ERROR_MSG ####} compiler directive. This generally is placed at the top of the questionnaire but can be placed before any question where you’d like to use a custom error message.


{!ERROR_MSG 1512 You MUST enter some text! }

This will display “You MUST enter some text!” instead of the default Survox message whenever message #1512 is invoked.

To control multiple language error messages, use the following syntax:

{!ERROR_MSG 1512
fr1512 Vous devez entrer un texte
1512  You MUST enter some text }

This will display “Vous devez entrer un texte” instead of the default “You MUST enter text” when that Survox error message displays in “French” mode.

The structure of the error message must follow the structure of its counterpart in msgfile.raw including the %s %d, etc. The %<letter> can go anywhere within the message as long as there are an equal number from the original message.

For example, 3 %<letter> in the original must have the 3 %<letter> in the new message.

The character limit for this compiler directive is 2000 total, inclusive of system variables such as %s and %d.

You can also edit the Survox “msgfile” directly if you want these messages to be a permanent part of your system. If you open it, you will notice a list of the languages there are error messages for. If your language is not on that list, select any unique two letters for your language.

Not all messages in the msgfile appear to interviewers/respondents conducting surveys. So, the best practice is to find the errors commonly used in your shop for immediate translation, and add others as needed.

To change a particular message, search for the appropriate error message using your text editor. Add your newly translated error message BEFORE the original English message, pre-pending the language letters to the message number. Your new msgfile will not compile successfully if your error message is in the wrong location in the raw file.


ge2602 M*** das ist alles ***
fr2602 M*** C'est tous! Au revoir! ***
sp2602 M*** Somos finito! Adios! ***
2602 M*** That is All ***

NOTE: Be sure to retain all Ms and %s and other programmatic formatting.   Ask Support for more information on modifying msgfiles.

Index Page

For web surveys, we recommend using multiple index pages, where each represents a language from the survey.  In some cases, a master index page is created with a link to each <language> index page, so the respondent can choose their language prior to entering the survey.

To specify a language within the index page, a hidden LANGUAGE input is required with a value equaling the two-character language code.


<input type="hidden" name="LANGUAGE" value="fr" />

In this example, the input will immediately set the language to FR when the respondent enters the survey.

Specifying the “LANGUAGE” hidden input is equivalent to having a {!SYSTEM,SET_LANGUAGE,<langcode>} in your qpx: the system automatically sets the language to the value of the tag, which must be a two-digit code. However, the system knows the language right after the index page has been submitted. Therefore the program can display the appropriate language even before the respondent is in the survey (in the error.tmpl file, for example).

If you have a survey that can be undertaken in various languages and let the respondent choose the language, we recommend to have a single entry point, e.g: index.html, where the respondent chooses the language; clicking on the appropriate choice/button on the index.html would lead to the chosen index page with the appropriate hidden input value for LANGUAGE.

We recommend having as many index pages as many languages you have; the setup is fairly simple as the index pages only require the correct hidden inputs.

Let’s say you were running a multi-language study in the U.S., Europe, Japan, and the languages are English, French, German and Japanese. The URL’s would look like:

Each language Index page would have the following hidden LANGUAGE input type:

<input type="hidden" name="LANGUAGE" value="en" />,
<input type="hidden" name="LANGUAGE" value="fr" />,
<input type="hidden" name="LANGUAGE" value="de" />,
<input type=”hidden” name=”LANGUAGE” value=”jp” />

Template Files

Web survey users need to take into consideration proper language handling in the template files. Usually only webSurvent users need to worry about translated template files but they can be used for webCATI studies as well.

There are two methods in setting up the template files.  You can have a set of templates for each language or you can have one set that contains >IFDEF’s for each language.  Both methods are described below.

  Method 1

If you choose to have a set of templates for each language, we recommend setting up a template sub-directory for each to hold the files.  The sub-directories should be named with the same two-character code used in the index pages and spec.  Once a translated set of template files is created, they can be used for all multilanguage studies that use that language.  We also recommend using the same approach for study-specific language templates, like the pagetop.tmpl.  Create the same two-character sub-directory in the <study> directory for all study-specific language templates.

The language specific templates are called in on the index page using a hidden input called TMPLS_DIR.


<input type=”hidden” name=”TMPLS_DIR” value=”$CFMC/websurv/tmpl/skin/skin_fr/” />

The above will use a set of templates translated in French for the French portion of the study.

  Method 2

If you choose to have one set of template files, you will need to set up HTML_DEFINES in your spec that will be used with >IFDEF’s in the template files.  The HTML_DEFINE will pass the necessary information to the template file.

You can get the current language of the survey by using the !SPECIAL,STUDY_INFORMATION,110,2 command.



CURRENTLANGUAGE will hold the two-character language code that specifies the current language of the study.  Then you can set an HTML_DEFINE for the current language to be passed into the template files.



And in the template files use the following >IFDEF commands:

Display English Text here 
Display French Text here
Display Spanish Text here

You can also use defines in the template files to be more efficient. One application can be change the language text where necessary.

For example in the buttons.tmpl you can have the following to change the language on each button:


<table border="0" align="left" cellpadding="0" cellspacing="0" width="75%">
<td width="20%">
<input type="submit" name="next.x" id="next.x" value="@next">
<td width="20%">&nbsp; </td>
<td width="20%">
>ifdef @backup_allowed
<input type="submit" name="previous.x" id="previous.x" value="@previous">
<td width="20%">
>ifdef @suspend_allowed
<input type="submit" name="suspend.x" id="suspend.x" value="@suspend">
<td width="20%">
<input type='button' name='help' id='help' style='background:#006699;color:#e3e9f0' value="@help" onclick='pop_help();'>


The pagetop.tmpl may need a META tag setting the proper encoding for all browsers to read.  The pagetop.tmpl used by a study is located in the study directory created by the Console, under the mode selected.  For example, /home/cfmc/studies/acme/a1234/websurvent/ would hold the pagetop.tmpl for the client Acme’s job a1234 online study.  If in multi-mode, both the /websurvent/ and /webcati/ pagetop.tmpl files will need to be updated.

Set this at the top of the pagetop.tmpl file:

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

If you are using Right-to-Left languages like Hebrew or Arabic, you will need to assign the DIR property to your HTML element with a Right to Left value (RTL):

<html dir=”RTL”>

This will right-justify all text and reverse the order in which the text is displayed.

NOTE: When combining a RTL language with English text, the English characters will NOT be reversed, the words will simply appear in the opposite order.

Below is an English and Arabic sentence, shown LTR and then RTL:


Note the right-justification and odd appearance of the English text. The layout seems unusual because the English words are reversed but their characters are not, but this sentence is correctly displayed for a RTL page.


The error template is used to display errors that occur prior to the respondent entering the survey, such as the use of an invalid password.  Because the error appears before the Survent process has started the survey, messages from the error.tmpl cannot be defined or customized in the spec.  Multilanguage login errors must be built into the msgfile.

To customize an error.tmpl file to work with multiple languages, you can use a series of >IF statements with a @LANGUAGE define.  These statements will pick up the language supplied by the hidden input on the index page, and display the appropriate text in the error.tmpl.


If we specify Italian in the index page:

<input type="hidden" name="LANGUAGE" value="IT"/>

We can then utilize the >IF @LANGUAGE syntax to display only Italian text in the error.tmpl, like this:

>IF @language="IT"
Si è prodotto un errore! <br/> 
@error_text <br/>
Per cortesia descrivete il problema nel maggiore dettaglio possibile.

This syntax can be used in all template files, but when used in the error.tmpl of your default skins, it allows you to create an error.tmpl that can work for several languages at once. The @ERROR_TEXT define will pipe in the appropriate Italian error message from the msgfile.

JavaScript Error Messages

Users fielding multilanguage surveys will also want to review and edit the Javascript error messages.  You can modify the cfmc_error_messages.js file with the language translations and rename it appending the two-character language code to the end.


cfmc_error_messages_sp.js for Spanish translations
cfmc_error_messages_de.js for German translations

Survox sends out a set of eight translated cfmc_error_messages.js files with each installation package for the most popular languages used and these can be found in the /var/www/html/cfmcweb/jquery/js directory:

  • Bulgarian: cfmc_error_messages_BG
  • Czech: cfmc_error_messages_CZ
  • French: cfmc_error_messages_FR
  • German: cfmc_error_messages_DE
  • Greek: cfmc_error_messages_GR
  • Italian: cfmc_error_messages_IT
  • Norwegian: cfmc_error_messages_NO
  • Spanish: cfmc_error_messages_SP

These get called in from the pagetop.tmpl and should be put AFTER the user_settings_jquery.js file to use the language specific javascript error messages instead of the English javascript error messages.

You can edit the pagetop.tmpl with the correct pathing for all of the cfmc_error_messages.js files or use an HTML_DEFINE to call in the correct error message files.

These can be called in using >IFDEF statements:

<script type=”text/javascript” src=”/cfmcweb/jquery/js/cfmc_error_messages.js”></script>

<script type=”text/javascript” src=”/cfmcweb/jquery/js/cfmc_error_messages_fr.js”></script>

<script type=”text/javascript” src=”/cfmcweb/jquery/js/cfmc_error_messages_sp.js”></script>

Language Control and Mentor

To control the default language used in a Mentor run, you must use the language META command at the top of your spec:

>language speaking=<language code>

When running SCAN or REFORMAT on a Multilanguage spec, it is important to output and save your run and add this command.