How to internationalize exams2nops() by adding support for new natural languages in written R/exams (that can be automatically scanned and evaluated).

Idea

In addition to completely customizable PDF output, R/exams provides a standardized format called “NOPS” for written exams with multiple-choice (and/or single-choice) exercises that can be automatically generated, scanned, and evaluated. In order to assure that the automatic scanning works the title page has a fixed layout that cannot be modified by R/exams users. However, to internationalize the format there is a possibility for customizing the natural language support. A number of languages is already available but it is not difficult to add further languages or to tweak existing languages if desired.

Example

To illustrate how the language support works, once it has been fully incorporated into the exams package, we set up a short exam with three exercises: deriv2, tstat2, swisscapital. All of these are readily available in the package (and are actually in English).

library("exams")
myexam <- c("deriv2.Rnw", "tstat2.Rnw", "swisscapital.Rnw")

Then we set up PDF output in English (en), German (de), and Spanish (es). By setting language most text on the title page is modified, only the name of the institution and the title of the exam have to be set separately. For the English example we produce n = 1 PDF output file in the output directory nops_pdf (created automatically).

set.seed(403)
exams2nops(myexam, n = 1, language = "en",
  institution = "R University", title = "Exam",
  dir = "nops_pdf", name = "en", date = "2018-01-08")

Then we do the same for the other two languages.

set.seed(403)
exams2nops(myexam, n = 1, language = "de",
  institution = "R Universit\\\"at", title = "Klausur",
  dir = "nops_pdf", name = "de", date = "2018-01-08")
set.seed(403)
exams2nops(myexam, n = 1, language = "es",
  institution = "R Universidad", title = "Examen",
  dir = "nops_pdf", name = "es", date = "2018-01-08")

The title pages of the resulting PDF files then have the desired languages.

Language specification

To add a new language, essentially just a single text file (say lang.dcf) is needed containing suitable translations of all the phrases on the title page as well as a few additional phrases, e.g., occuring in the HTML evaluation reports etc. As an example, the first few phrases in English (en.dcf) are:

PersonalData: Personal Data
Name: Name
FamilyName: Family Name
GivenName: Given Name
Signature: Signature
RegistrationNumber: Registration Number
Checked: checked
NoChanges: In this section \textbf{no} changes or modifications must be made!
...

And the corresponding translations to German (de.dcf) are:

PersonalData: Pers{\"o}nliche Daten
Name: Name
FamilyName: Nachname
GivenName: Vorname
Signature: Unterschrift
RegistrationNumber: Matrikelnummer
Checked: gepr{\"u}ft
NoChanges: In diesem Feld d{\"u}rfen \textbf{keine} Ver{\"a}nderungen der Daten vorgenommen werden!
...

Note that here LaTeX markup is used for the German umlaute and for bold highlighting. Alternatively, special characters can be added in a suitable encoding (typically UTF-8) but then the encoding has to be declared when calling exams2nops() (e.g., encoding = "UTF-8").

Most of the phrases required in the .dcf are very straightforward and only some are a bit technical. There are also a couple of coordinates (MarkExample*) necessary for aligning some text lines. If you have set up your own lang.dcf you can easily pass it to exams2nops() by setting language = "/path/to/lang.dcf". The same has to be done for nops_eval() when evaluating the exam.

Currently available languages

Due to the kind support from friends and various dedicated R/exams users, there is already support for many important Western languages as well as a few other languages/countries. All of these are directly available in the R package (note that "tr" requires the current development version from R-Forge, though). But for convenience and manual inspection the .dcf files are also linked here.

Contributing new languages

If you want to contribute a new language, simply set up a .dcf file starting out from one of the examples above and send the file or a link to . Do not worry if not everything is 100% perfect, yet, we can still sort this out together! For Western languages (e.g., dk, se, no are still missing) it is probably the most robust solution to code special characters in LaTeX. For languages requiring other alphabets (e.g., ru would be nice or Asian languages…) it is probably easiest to use UTF-8 encoding. Get in touch through e-mail, the support forum or on Twitter (@AchimZeileis) if you want to know more or need further details.