====== Multilingual Surveys  ======

In a multilingual survey, you can easily deposit one or more translations for all visible texts (e.g. questions, text modules, scale labels, error messages). 

The [[:en:survey:url|link to the questionnaire]] may either specify the language to show or, if not, the respondent will see a selection of all available questionnaire languages.

**NOTE:** Each question can contain multiple language versions (see more in this chapter). You __must not__ make any copies of questions, sections or text moduls for a new language version. 

===== Creating a Multilingual Survey =====

First, create your questions and the questionnaire. The language used to create the first version of the questionnaire is called //base language//.

In **Survey Project** -> **Project Settings** now click //Add another Language//.

{{:en:create:scr.multilang.add.png?nolink|Add a translation}}

Now select the language, you would like to translate the questionnaire to. If more than one language is used in the survey, the **Control** menu will show the item **Language Versions**.

{{:en:create:scr.multilang.control.png?nolink|Language Versions in the Menu}}

Using **Manage Language Versions** you can now select the language to primarily use for editing (see below for details). Please select the language you have added.

**Tip:** You are working in the questionnaire and the menu item **Language Versions** is not selected? Just move the mouse pointer over the menu item and wait a second for the menu to open. Now, you can comfortably click one of the language symbols to change the editing language.


===== Translating the questionnaire I =====

Select **language versions** -> **help for translation** in the **navigation** field. Each text that appears in a question, an item or a text module will be listed here. You can see the default language on the left side and the active language version on the right side. If, however, the default language is active, the first language to come along will be displayed.

Fill in the translation on the right side and save (below). To save time you may (the support of the server provided) select //automatic translation// -- only the weaknesses of automatic translation have to be straightened.

**Note:** In case you take notice of any mistakes in the default language: Changes on the left side will also be saved.

===== Translating the questionnaire II =====

In case of outsourcing the translation select the menu item **language versions** -> **import translations**. All the texts of the questionnaire can be exported as a table (CSV-file), translated externally (e.g.: by a translation office)and be reimported as translations. 
Proceed as follows:

  - **language versions** -> **import translations**
  - You must make the necessary settings in the menu item //export texts// then clicking on  //download//
  - You receive a CSV-file that you can open with almost every spreadsheet software (e.g. OpenOffice Calc, Excel). If the question of formatting comes up:
    * encoding/character set: Unicode (UTF-16 LE)
    * seperated by a tab
    * text delimiter are quotation marks  (''"'')
  - Save the table in a format of your choice and send the file to a translator
    * **Note:** During the translation process the left column must not be changed. It serves the assignment of texts. The questionnaire should not be changed either.
  - Save the table with the translations as a CSV-file
    - **Note:** It is quite difficult encoding international characters to UTF-8 in an Excel file. However, if you use Excel and are in need of non-European characters save as  "Unicode (*.txt)" and import this file with the encoding "UTF-16LE" (//separator:// "tab"). It is more reliable to save the Excel file as CSV by using the freely available OpenOffice Calc -- it functions in a manner similar on MacOS with Numbers (iWork Suite).
  - **language versions** -> **import translations**
  - Select the CSV file in the menu item //import translations// and specify whether already existing translations should be updated. 
    * **Note:** If  there is no entry  in a translation sheet on the right column, this row will be ignored during the import. Existing translations will not  be deleted on any account.
  - After clicking on //import// you will be asked for the format of the CSV file. Normally SoSci Survey independently recognizes the format and you have only to confirm.
  - SoSci Survey asks for the languages of the sheet's columns, if the first row of the translation sheet  __does not contain__  the three letter language code of the respective language version.
  - After confirming with //import// the translations will be imported and saved in the survey project.
    * In case of changing texts in the sheet or in the survey project an assignment might be impossible. In this case SoSci Survey shows after the import a list of texts that could not be assigned.
    * If a text cannot be assigned 1:1 SoSci Survey proceeds as follows: First it deletes quotation marks and space from the reference text, then punctuation marks and HTML tags to find the suitabele text. Please check, if necessary after the import under **language versions** -> **help for translation** whether any HTML tags will have to be complemented.
===== Translating the questionnaire III =====

  * Open a new question in the questionnaire. From this point on there will always appear a country flag next to the text entry field. It symbolizes the current language version.

{{:de:create:scr.translation.textinput1.png|Eingabe mehrsprachiger Texte (1)}}

  * Click the flag to show the original text.

{{:de:create:scr.translation.textinput2.png|Eingabe mehrsprachiger Texte (2)}}

  * You can change between the language versions of this text element by clicking on the respective flag. 

**Note:** You do not define the active language version by using the flag, but merely the language version for the current text entry field. The element saves all texts you fill in for the respective languages -- it depends on the language(s) offered and then selected by the  __participant__ which text will be shown in the questionnaire.

{{:de:create:scr.translation.textinput3.png|Eingabe mehrsprachiger Texte (3)}}

  * It does not matter which language version of your project you are currently editing, you can make modifications any time to any language version(with the exception of **legal notice and logo**). By saving the question all language versions of it will be updated automatically.
  * At the bottom of each question you can see its items and selection options. Please consider that the usual  **fast entry** will only be offered if you have determined the default language under  **language versions** → **language administration** and the language to be edited activated (recognizeable by the pencil icon). A help for translation of the items resp. selection options appears in the translation mode. On the left side there is the default language whereas on the right side is the editing language.

{{:de:create:scr.translation.items.png|Items und Optionen übersetzen}}

Now you can translate the questionnaire step by step. Leave the original text open so you can keep an eye on it. The translation process will be completed even faster by using  **help for translation** (in the **language version** set-up). It shows existing texts, blank fields for the translation and offers a raw machine translation if asked.

===== How to use language versions in the questionnaire =====

After the translation process you are basically done. Now, the prepared questionnaire supports both language versions. You have three options for the selection of the preferred language version:

  * You can select a language in the set-up of the questionnaire(**questionnaire set-up**, tab **settings**). The questionnaire will always start in the selected language version.
  * You can include a note for the language(s) in the [[:en:survey:url|link to the questionnaire]]. You can find the three letter language code of the respective language under ** language versions**. The codes correspond by the way[[http://www.loc.gov/standards/iso639-2/php/code_list.php|ISO 639-2]] (bibliographische Varianten). The preset language in the questionnaire takes precedence over the set language in the questionnaire.
  * You can also decide to not preset any language in the questionnaire set-up ("offer selection") and in the link to the questionnaire. This way the participant can select at the beginning of the survey between the languages available. You can administer the exact representation and texts of this language version under **language versions** → **language selection in the questionnaire**.

===== How to hide selection options resp. items=====

It may happen that there are different selection options in one language version than in an other.

This can be done by hiding the unnecessary items. These have to be preceded by a tilde(~). However, it is recommended to maintain the text in the default language since it is considered for labelling the dataset. In the translation it is enough to insert a tilde.

{{:de:create:scr.translation.hide_items.png|Items und Optionen in einer Sprachversion ausblenden}}

**Note:** In case you want to start with a tilde the item has to be preceded by two tilde(~~),the item will be shown starting with a tilde.
===== How to change language dynamically =====

If you want to change the language version during the survey process the PHP functions ''[[:en:create:functions:getlanguage|getLanguage()]]'' and ''[[:en:create:functions:setlanguage|setLanguage()]]'' are at your disposal. You can ...

  * hide entire questions in the respective language versions dynamically.
  * control the order of items depending on the language.
  * create your own language selection.

===== Non-Western Languages =====

The standard Western fonts may not contain all the characters you need for Chinese, Japanese, Indian, Persian, Hebrew, etc. The best solution is to add fonts with the appropriate characters in [[:en:create:layout|Questionnaire Layout]] for the fields //Default font size// and //Font for input fields// in the //General Settings//. For Simplified Chinese, the list of fonts could then look something like this:

    Arial, Helvetica, tahoma, verdana, 宋体, SimSun, 华文细黑, STXihei, sans-serif
    
In front in this example are additionally the western fonts. This __can__ be useful but does not have to be. It makes a difference especially when Western and non-Western characters are mixed in the questionnaire.

But you may also want to use a different font for the complete questionnaire (but only for a single language version). So e.g. "Arial" for the German version and "Sim Sun" (宋体) for the Chinese language version.

In this case, adjust the predefined text module //Layout: HTML-Code in <head>// under **Text modules u. Label**. Namely, you deposit the following HTML/CSS code for the Chinese language variant:

<code html>
<style type="text/css">
body,
textarea,
input,
select {
  font-family: 宋体, SimSun, 华文细黑, STXihei, sans-serif;
}
</style>
</code>

For other language versions you can of course store other definitions. If you do not specify anything, the definition from the layout is used.