Internationalization - method 1

See also Internationalization method 2. Method 1 is easiest for small questionnaires or when the number of languages is very small. For longer questionnaires or questionnaires that need to be translated into multiple languages, use method 2.

See also Localization for how to configure ViewsFlash's default language to a non-English language, such as Chinese, French, Arabic, etc..

ViewsFlash allows questionnaires and polls to be created and filled out in any language in the world. Internally, ViewsFlash uses Unicode. In the browser, it uses UTF-8 by default, unless you specify otherwise in the Language page.  If saving data as .txt files in the file system, it uses that character set. If saving to a database, the database converts Unicode to its internal representation. See Technical Specification for additional information.

Creating questionnaires in left-to-right languages
By default, questionnaires are created using the standard UTF-8 character set, displayed from left to right.

Right to left languages
- Create a questionnaire and use the Language page to set the right-to-left direction.
- The Language page also includes settings for setting the "lang=" tag and the "dir=" HTML tags, which specify the questionnaire's language and left to right or right to left direction.

Creating a questionnaire in a specific language
To create a questionnaire in a specific language other than the default ViewsFlash language, create it by adding "_ _ x x" to the original questionnaire's name.
For example, to create a questionnaire "Atitud" in Spanish only, name it "Atitud__es" (two underscorees, 'e','s'). The URL of the questionnaire will be the URL shown on the Publish page, as usual.
All the questionnaire validation messages, such as "answered required" will be shown in Spanish.

Translating a questionnaire into multiple languages
Create a multi-page questionnaire in its original language and name it as usual, with a name such as "Attitude". Publish and test the questionnaire. When satisfied, make a copy of the questionnaire for each language that the questionnaire will be translated to, using a special questionnaire name by adding "_ _ x x" to the original questionnaire's name. For example, if the original questionnaire is named Attitude, name the Spanish questionnaire Attitude__es (two underscores, 'e', 's'), and the French questionnaire Attitude__fr, etc. Then, translate the Attitude__es questionnaire using the Visual editor, and Publish the questionnaire. Each questionnaire will have its own URL; however, when the Submit button on the final page is pressed and the questionnaire is committed, the saved data and tallies will be stored in the underlying questionnaire, Attitude, rather than Attitude__es.

The codes used are ISO 639-1 Language Name codes as used by Java Locale. Reference: https://en.wikipedia.org/wiki/ISO_639-1

To analyze responses by language, create a question of type Hidden, and click on "Edit answers" at the bottom of the page to allow entering specific values. Enter the values with the language code of each language being used, and mark the language of each questionnaire as the default value by adding an asterisk, like this:
en
fr*
es
Questionnaires in the other languages modify this default value to indicate their language.

Validation messages and button legends such as "Please fill out this required field" and "Next", are internationalized using the lookupi18n tags, which are used throughout the ViewsFlash styles. These values, by default, are retrieved from a series of properties files described in Localization. These can also be translated using the Messages page without having to modify the properties files.

Directing respondents to the questionnaire in their language

Once the questionnaires in multiple languages are created, if there is a need to direct respondents to a single URL where they will choose the appropriate language for the questionnaire, follow this procedure.

Go to the Publish page for the original questionnaire, whose name does not end in __xx. Take the questionnaire URL and modify as described here. Example: starting with,
http://myserver.com/ViewsFlash/servlet/viewsflash?cmd=page&pollid=MyQuestionnaires!Attitude

Insert the following between ViewsFlash/ and servlet :

i18n.jsp?i18n-url=

so that the result is

http://myserver.com/ViewsFlash/i18n.jsp?i18n-url=servlet/viewsflash?cmd=page&pollid=MyQuestionnaires!Attitude

When participants go to that URL, they will see:

After the participant selects their language and presses Go, the browser redirects to the questionnaire in the chosen language. Only those languages for which a questionnaire is available are displayed in the menu, and the languages are displayed in their native name and character set. Chinese displays 中文, Arabic displays العربية and so on.
If only one language is available, this page redirects to the questionnaire immediately, without presenting the language choices.
If any required parameters are incorrect, or the pollid of the questionnaires is incorrect, this page does not display anything.

Additional parameters can be inserted in the URL, like these:
i18n-submit=Va!&i18n-title=Asesoria del Otoño&i18n-choose=Escoja su idioma&i18n-language=Español&

so that the result is

http://myserver.com/ViewsFlash/i18n.jsp?i18n-submit=Va!&i18n-title=Asesoria del Otoño&i18n-choose=Escoja su idioma&i18n-language=Español&i18n-url=servlet/viewsflash?cmd=page&pollid=MyQuestionnaires!Attitude

This will display a page appropriate to a questionnaire where the most common language is Spanish, and looks like this:

The additional parameters are:
i18n-title is the title. Default is no title.
i18n-choose is the text for the dropdown menu showing the languages that the questionnaire is in. Default is "Choose questionnaire language".
i18n-language is the original questionnaire's language. Default is the language of the server's Locale, such as English. It is the first choice in the drop-down menu.
i18n-submit is the text to use in the button. Default is "Go".
i18n-url is everything to the right of the original ViewsFlash/ . This parameter is required.

All the URLs used in the Publish page are allowed. This example uses https, a port, a custom web application name instead of ViewsFlash,
and J2EE authentication (through servlet/vfauth):

https://myserver.com:88/MyWebAppName/i18n.jsp?url=servlet/vfauth?cmd=page&pollid=MyQuestionnaires!Attitude

Installation note: servlet parameter apiattribute=com.cogix.vwf.api must be used to use i18n.jsp. If it is not, the message "Questionnaire not open" will be displayed.

Database and servlet parameters

An appropriate database encoding must be chosen. We recommend using UTF-8, which supports all languages.

Oracle setup: The default setting for Oracle 8.1.7 is "WE8ISO8859P1", which corresponds to ISO-8859-1. For other languages, create the database used by ViewsFlash with UTF8 encoding and add the following line to viewsflash.properties:
dbcharwidthmultiplier=3.
If a database has not been created with UTF8 encoding, you must export it and import it -- there is no way to convert one on the fly. For this reason, if there's any possibility of questionnaires being created in languages other than ISO-8859-1 in the future, create the database with UTF8 at the outset. Other applications that access questionnaire data stored by ViewsFlash will work fine if they are Unicode compatible. To find out what encoding your database uses in Oracle, use:
select parameter, value from nls_database_parameters where parameter=NLS_CHARACTERSET';

Technical Specification

Internally, ViewsFlash always processes all text as Unicode. On the browser, it uses UTF-8 as its default encoding. Very old application servers may require specifying a more specific encoding; in that case, specify it using the Language page.

Browsers
To conduct questionnaires in languages other than English use IE5, Firefox 1, Opera 6, or Netscape 6, Safari 1.2 or higher. The browser must have the appropriate fonts and language packs installed to be able to view a page in the desired encoding.

Each browser must also have a way to enter international characters, such as a language-specific keyboard, a "compose" key, or Windows Input Method Editors (IME) -- see Regional Options/Input Locales in the Windows Control Panel. In Unix workstations, logging in with the correct Locale will adjust the keyboard properly.

Saving questionnaire results as .txt files
Questionnaire data can be viewed as usual from the Live Data page. Questionnaire response data is stored in these files using the specified encoding. Other applications can use these files provided they take that into account.

The Language page determines the character set to use when displaying and receiving data from a questionnaire or defining that questionnaire. The default is UTF-8. When a questionnaire specifies a character set in the Language page, the following things happen:

- internally, the ViewsFlash application keeps all text as 2-byte, Unicode Strings.

- all ViewsFlash pages include an HTTP header that specifies that character set. From this, the receiving browser knows the intended encoding. Example of a Content-Type header:
text/html; charset=UTF-8

- all HTML pages created by ViewsFlash include a <meta> tag with the specified character set. For example:
<meta http-equiv="Content-type" content="text/html; charset=utf-8">

- all voting forms and application HTML pages include a hidden field 'charset'. ViewsFlash uses this field to decode the received form input to Unicode, and it is therefore essential. Example:
<input type="hidden" name="charset" value="Big5">

- questionnaire data stored in .txt files is encoded into the indicated character set.

- questionnaire data stored in a database is not encoded; the database encodes and decodes Unicode characters. In Oracle, when using character sets other than ISO-8859-1, this requires defining the database to use "utf8" as its encoding, and adding the dbcharwidthmultiplier=3 servlet parameter to the viewsflash servlet. Because of this, the values of answers are restricted to 10 characters instead of the usual 30, and the values of freeform text answers are restricted to 666 characters, unless the dbmaxvarchar=4000 servlet parameter is used to increase this number to 1333.

Earlier versions of ViewsFlash suggested using very specific Language codes, such as ISO-8859-7. It is much more reliable to use UTF-8, which is now the default, and to use a different character set in the Language page only if UTF-8 fails, which is very rare.

Next:  Internationalization 2