Converting Pages to Support Translation

Translation is done utilising key value pairs under the i18n package in the Security Shepherd Project. When a user selects a language or the value from the browser header "Accept-Language" is received by the server the translation kicks in and translates the application on the session level. Translation is done using the Java JSTL library under lib/jstl-1.2.jar.

Property Files

The key value pairs are stored in .properties files in i18n package which is structured to match that of the JSP files so that managing translation does not get out of control.

English Strings are stored in files that contain no underscore;

zf8ed52591579339e590e0726c7b24009f3ac54cdff1b81a65db1688d86efb3a.properties

which contains the key = value

title.question.xss = What is Cross Site Scripting (XSS)?

example.xss.1 = &lt;SCRIPT&gt;<a>alert(&#39;XSS&#39;)</a>&lt;/SCRIPT&gt;

As you can see you displaying and rendering HTML is not an issue here

I've tried to make keys as descriptive as possible with formats like;

• title.question
• paragraph.text
• sentence.info

This helps in the long run when looking at JSPs that no longer contain English Strings

If you are translating for a particular language you need to copy the English file and append and underscore plus the country code you are translating for. An example of which can be seen in the XSS level;

• English = zf8ed52591579339e590e0726c7b24009f3ac54cdff1b81a65db1688d86efb3a.properties
• Spanish = zf8ed52591579339e590e0726c7b24009f3ac54cdff1b81a65db1688d86efb3a_es.properties
• Irish = zf8ed52591579339e590e0726c7b24009f3ac54cdff1b81a65db1688d86efb3a_ga.properties
• Chinese = zf8ed52591579339e590e0726c7b24009f3ac54cdff1b81a65db1688d86efb3a_zh.properties

Once you've copied the English file and appended the underscore plus country code then you can start adding the translation by changing the value. Do not edit the key!

JSP

On a JSP page you need to change the encoding from iso-8859-1 to UTF-8 (at the minute this is needed to support Chinese but in the future this will support other languages too)

At the top of your JSP page remove (If Exists);

<%@ page contentType="text/html; charset=iso-8859-1" 

And replace with

<%@ page contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"

Then make sure you are importing at least the following packages;

<%@ page import="java.util.Locale, java.util.ResourceBundle, utils.*"%>

Add the following jsp scriptlet so that the language is set for the page from the session

<% Locale locale = new Locale(Validate.validateLanguage(request.getSession())); %>

You then need to reference the property file containing the key values pairs. The example below pulls in the key values from the XSS level property file.

<%
String levelHash = "zf8ed52591579339e590e0726c7b24009f3ac54cdff1b81a65db1688d86efb3a";
ResourceBundle bundle = ResourceBundle.getBundle("i18n.lessons.m_reverse_engineering." + levelHash, locale);
%>

On each page you need to replace the English string with a scriptlet like so

<%= bundle.getString("title.question.xss") %>

What's happening here is you're referencing the key title.question.xss which the value in English is "What is Cross Site Scripting (XSS)?"

That's it just replace all the English strings with the scriptlet mentioned above and you're done. Reach out to the Security Shepherd community to have your level's properties file translated

Servlets

In Shepherd not all Strings come from JSP. Some are returned by Servlets making the process for translating different. You still use the .properties files but in the Servlet code you firstly need to import some libraries;

import java.util.Locale;
import java.util.ResourceBundle;

You need to retrieve the locale setting from the users session. You can use this line to achieve this (This code will default to English if there is no setting on the session)

Locale locale = new Locale(Validate.validateLanguage(request.getSession()));

You need to then create and point a ResourceBundle to the location of the .properties files you wish to use and pass in the locale variable.

ResourceBundle bundle = ResourceBundle.getBundle("i18n.text", locale);

Finally when outputting any strings, reference the key within those .properties files. eg;

String htmlOutput = "<h2 class='title'>" + bundle.getString("response.hackDetected") + "</h2>" +
"<p>" +	bundle.getString("response.hackDetectedMessage") + "</p>";
out.write(htmlOutput);