Skip to main content
Kinetic Community

Implementing a Multi-Language Survey

Import Files
Survey Multi-LanguageSurveySample
Translation Files LanguageTranslationFiles.zip
Theme Theme
There are two main methods of implementing a multi-language survey. Option one is to build the one survey and then clone it for each additional language.  Edit the cloned versions, replacing the displayed text with the appropriate language-specific value. Option two is to make some framework changes to allow a single survey to be translated to multiple languages. Each of these methods has pros and cons, but making framework changes to support multi-language surveys is a bit more involved than simply cloning the survey and changing the displayed text.  The biggest benefits are that once these framework changes are done, it is easier to make changes to the survey and to implement additional multi-language surveys in the future. This article will focus on how to implement framework changes to enable multi-language surveys.

Description

Overview of the translation process

These framework changes introduce functionality that basically performs a find-and-replace before the survey is displayed to the end-user.  The code performs the following steps.

  1. Determines what language should be displayed
  2. Retrieves the language replacements
  3. Applies the translations

Overview of framework changes made

These are the high-level actions that need to be completed to implement the framework changes and enable a survey to take advantage of them.

  1. Create a new theme directory
  2. Adjust the JSP within the theme
  3. Adjust the survey
  4. Create and deploy the language translation files

Details

  1. Create a new theme directory on each web service by copying and unzipping the attached survey.zip file into the <kinetic install path>\webapps\kinetic\themes directory.
    Survey Theme Directory.png
     
  2. Review and compare the displayPage.jsp and the diaplayPageInternational.jsp files located in the <kinetic install path>\webapps\kinetic\themes\survey directory.

    Review Display Page JSP.png

Note that the displayPage.jsp file is the Out of the Box version while the displayPageInternational.jsp file has been created in order to provide the functionality for a multi-language survey.

The following changes were made based on the standard out-of-the-box displayPage.jsp and were used to create the displayPageInternation.jsp file.  You will want to either apply similar changes to your existing custom JSP page, or you will want to make further changes to this one to incorporate your style sheets, etc.

  1. After <!DOCTYPE html> line, this code was added to incorporate the logic necessary to determine what language the survey should be presented in as well as retrieving the appropriate language translation file.
<%@include file="includes/localize.jspf" %>
<%@include file="models/base.jspf" %>
<%
String currentLang="";
if (request.getParameter("lang") != null) {
       currentLang=request.getParameter("lang");
} else {
       currentLang="en";
}
java.util.ResourceBundle templateResourceBundle=null;
try{       templateResourceBundle=ThemeLocalizer.getResourceBundle(customerSurvey.getSurveyTemplateInstanceID()+".template", currentLang);
} catch (Exception rbe){
}
String i18nValues = "";
if (templateResourceBundle != null){
       for( java.util.Enumeration en = templateResourceBundle.getKeys(); en.hasMoreElements(); ){
              String key = (String)en.nextElement();
              if (key.indexOf("javascript.")>=0){
                     String keyVal=key.replaceAll("javascript.", "");
                     if (i18nValues!=""){
                           i18nValues+=",";
                     }
                     i18nValues += "\""+keyVal+"\" : \""+templateResourceBundle.getString(key)+"\"";
              }
       }
}
%>
  1. A CSS file reference was added at line 62.  This CSS page only includes content to format a table at the top of the sample service item.  If you want to use this JSP page for your own survey, you can either add to this CSS file, add an additional CSS file reference, or replace this with your own CSS file.
<link rel="stylesheet" type="text/css" href="<%=request.getContextPath() + "/themes/survey/survey.css"%>"/>
  1. At line 65, a function was added to allowing the user to switch the display to another supported language by clicking an option on the page.
<script type="text/javascript">

       function renderInLanguage(language) {

              if (clientManager.customerSurveyId!=null && clientManager.customerSurveyId!="null") {

                     window.location = "DisplayPage?csrv="+clientManager.customerSurveyId+"&lang="+language;

              } else {

                     window.location = "DisplayPage?srv="+KD.utils.ClientManager.templateId+"&lang="+language;

              }

       }

</script>
  1. Replaced the line <jsp:getProperty name="customerSurvey" property="questions"/> with the text below.  This retrieves the survey content and initiates the translation process.
       <%

              com.kd.ksr.beans.Page ppage = com.kd.ksr.cache.PageCache.getPageByInstanceId(customerSurvey.getSurveyTemplateInstanceID(), customerSurvey.getPageInstanceID());

              SimpleEntry[] questions = ppage.getPageQuestions();

              String pageContent = customerSurvey.getQuestions();

       %>

          <%@include file="pageFragments/templateLocalize.i18n.jspf" %>

          <%= pageContent %>
  1. Adjust the survey

For clarity, a sample survey has been attached to this article.  It uses the ‘survey’ theme that was created in step 1, and demonstrates how to adjust any survey to take advantage of the language translation functionality.  (The survey is placed in the ‘Kinetic Data Examples’ category.)

 

  1. Import the sample survey “Multi-language Survey Sample”
    Import Survey.png
     
  2. Review the sample survey to identify if any changes are needed on your survey.
    1. Question labels do not need any action (unless they include special characters such as parenthesis).
    2. Text elements: <LOCALIZE_TEMPLATE> [your text here] </LOCALIZE_TEMPLATE> tags need to surround any text that you want translated.  This could include instructional text, thank you text, etc.
      Text Elements.png
       
    3. List values:  <LOCALIZE_TEMPLATE> [your text here] </LOCALIZE_TEMPLATE> tags need to surround all text that you want translated in the label of the list choice – not the value.
      List Elements.png
       
    4. Review the text element “Language Table”.  You will need a way for your users to select the language in which they want their survey to appear.  While the link a user receives via email (or another method) may direct the survey to open to a specific language, this will allow users to switch as necessary. The sample survey presents a list of clickable language choices in a horizontal table.
      Language Table.png
       
    5. Ensure the survey uses the revised JSP by adjusting the “Display Page (JSP)” field on the Advanced tab (/themes/survey/displayPageInternational.jsp).
      Display Page JSP.png
       
  1. Create and deploy the language translation files

The language translation files are where you define the replacement text.  The file is nothing more than a text file containing the “lookup” value (the original text) and the “replacement” value (the translation text).  All language files are put in a directory that is named to correlate to with the survey’s unique GUID.  For this example the GUID value is: KS00505696001CzEkSUguQWUDQLroH
 

There are a couple of important rules when creating a translation file:

  • All spaces in the lookup need to be replaced with underscores.  During the translation process, the system will retrieve the source text, replace spaces with underscores and attempt to find a matching within the translation file.
    • Ex:  The lookup value for “What is your name?” will be “What_is_your_name?”
  • The replacement values for non-Latin-based languages (Polish, Russian, Chinese, Japanese, etc.) need to be translated into Unicode values.  (Use a website to assist with the Unicode translation, such as http://code.cside.com/3rdpage/us/javaUnicode/converter.html)
    • Ex:  The question “What is your name?” will be “\u4F60\u53EB\u4EC0\u4E48\u540D\u5B57\uFF1F”
  • Files are located in \<kinetic install directory>\webapps\kinetic\WEB-INF\classes\ in a  subdirectory named the same value as the survey’s instance ID.
    • Ex: \<kinetic install directory>\webapps\kinetic\WEB-INF\classes\KS00505696001CzEkSUguQWUDQLroH
      Language Translation Files.png
       
  • Within the subdirectory, the files are always named template_[language code].properties
    • Ex: template_es.properties is the Spanish translation file.
      template_es properties.png
       
    • Ex: template_fr.properties is the French translation file.
      template_fr properties.png
       
  • Language translation files need to be manually deployed to each web server.  Depending on configuration settings, the web server(s) may need to be restarted to pick up changes to the language translation files.

 

  1. For the sample survey, unzip the sampletranslationfiles.zip directory and copy it to \<kinetic install directory>\webapps\kinetic\WEB-INF\classes folder.  Please note that you may need to create the classes folder.

 

 

Open the survey

To open it in English, click the ‘Open Anonymous’ button.  To change the language, click on one of the languages at the top of the screen.

English:

Survey English.png

 

Spanish:

Survey ES.png

 

French:

Survey FR.png

To open the survey in a specific language, copy the anonymous URL, and add the parameter &lang=[2-character language abbreviation] (i.e., lang=fr).  Use this method when sending notifications to users so they can initially access a form in a specific language.