Translating Security Shepherd¶
This page is for contributors who want to help translate Security Shepherd. There are two kinds of work:
- Making text translatable (for developers). Much of Security Shepherd's English is still written directly into its pages and servlets, including every Admin page and every message the server sends back. That text has to be moved into translation files before anyone can translate it. See Make text translatable.
- Translating (for anyone who knows a language). Translating the text that's already in translation files, or adding a language.
Translations describes what players and organisers see today.
How a page gets its language¶
flowchart LR
menu["Language menu<br/>?lang=es"] --> session["Session: lang"]
browser["Browser's language<br/>(until one is chosen)"] --> session
session --> platform["Platform pages<br/>login, start page, scoreboard, …<br/><fmt:message> with i18n/text"]
session --> validate["Validate.validateLanguage<br/>(always English, #937)"]
validate --> levels["Level pages, servlets and level names<br/>ResourceBundle with i18n/lessons, i18n/challenges,<br/>i18n/servlets, i18n/moduleGenerics"]
- Platform pages include
translation.jsp, which stores the chosen language in the session and reads their text fromi18n/text.propertieswith JSTL's<fmt:message>. - Level pages, their servlets and the level names in the menu load their properties files with
ResourceBundle, in the languageValidate.validateLanguagereturns. That method currently returns English for every language, so they're always shown in English, whatever's chosen (#937). Their translation files are kept and still worth improving: they'll be shown once that's fixed.
A string missing from a translation is shown in English.
The files¶
The text is in src/main/resources/i18n/, in Java properties files. Each English file has a copy per language, with the language's ISO 639-1 code added to its name: text.properties is English, text_es.properties Spanish, text_ga.properties Irish.
| Files | Text |
|---|---|
text.properties |
The platform's pages and menus |
moduleGenerics/moduleNames.properties |
Level and topic names in the menus |
lessons/<topic>/<hash>.properties |
Each lesson's page |
challenges/<topic>/…properties |
Each challenge's page |
servlets/… |
Text the levels' servlets return, and error messages |
cheatsheets/solutions.properties |
The cheat sheets |
Each line is a key and its text:
Keep the key as it is, and translate only the text after =. Keep any HTML in the text, such as <a> or <, and placeholders such as {0}. Save files as UTF-8. Older files use escapes such as 中, which also work.
Improve a translation¶
- Find the English file for the page and its copy for your language. If there's no copy yet, copy the English file and add the language code to its name.
- Translate the text, or add the keys that are missing from the copy.
- Check it: run Security Shepherd locally, as in Getting started, choose your language in the menu, and look at the page.
- Open a pull request, as described in Development workflow.
To see which keys a language is missing, compare it with the English file. For example, for Spanish:
cd src/main/resources/i18n
diff <(grep -o '^[^#=]*=' text.properties | tr -d ' ' | sort) \
<(grep -o '^[^#=]*=' text_es.properties | tr -d ' ' | sort)
Add a language¶
- Translate
text.propertiesintotext_<code>.properties. The platform's pages are what every player sees, so start there. -
Add the language to the menu in
src/main/webapp/translation-select.jsp, in its own language: -
Translate
moduleGenerics/moduleNames.properties, the level names in the menu. They'll be shown once #937 is fixed. - Add the language to the table in Translations.
Make text translatable¶
This is the bigger job. As of 4.0, this text is still in the code:
| Where | Files |
|---|---|
| Every Admin page | src/main/webapp/admin/**/*.jsp: none of the 24 use a translation file. Only the Admin menu's labels, in index.jsp, do. |
| Every message from an admin action, such as "Class created" | src/main/java/servlets/admin/**/*.java: none of the 36 use a translation file |
| Messages from the platform's servlets, such as login and registration errors | src/main/java/servlets/*.java: only Setup uses a translation file |
| The scoreboard and error pages | scoreboard.jsp, lostSheep.jsp, serverError.jsp |
| Some sentences on otherwise translated pages | The platform's JSPs |
To move text into a translation file:
- Add a key and the English text to the right properties file:
text.propertiesfor platform and Admin pages, or the servlet's file underi18n/servlets/. - Replace the English in the code with a lookup of that key:
- A platform or Admin page includes
translation.jsp(<%@ include file="translation.jsp"%>, with the right relative path) and shows text with<fmt:message key="your.key" />. Admin pages are loaded into the start page, but each is a JSP of its own, so each needs the include. - A level page loads its bundle as
webLevelTemplate.jspdoes,ResourceBundle.getBundle("i18n.challenges.<topic>.<hash>", locale), and shows text withbundle.getString("your.key"). - A servlet loads its bundle with the locale from
Validate.validateLanguage(request.getSession()), asModuleServletTemplate.javadoes, and returnsbundle.getString("your.key"). Until #937 is fixed, that locale is always English.
- A platform or Admin page includes
- Check the page still reads the same in English, and that a language with the key shows it.
Name keys after where the text appears, such as title.question, paragraph.info.1 or button.hideIntro, so the page still reads clearly with only keys in it.
New pages, levels and servlets shouldn't add English to the code at all. Put every string in a translation file from the start.