Skip to content

Translations

It is proposed that the new CAWI will use i18next as the universal tool to handle the translation of strings within both the engine itself, the various display modules and multi-language surveys.

i18next has similar functionality to the "gettext" tool and has a large ecosystem around it including tools to aid in creating and editing translation files (including machine-translation).

Core translations/customisations

Each of the CAWI modules will have its own localisation "namespace" (e.g. "engine", "display"), and the language strings will be identified with translation IDs (e.g. "VALUEREQUIRED"). The individual language strings are stored in JSON files in the locales/{namespace}/{lng}.json files within the module's NPM package (and git repository).

Multi-language surveys

It is not yet agreed precisely how we want to manage multi-language surveys, but proposed workflow is as follows:

  • Based on the _xml and/or JSON files (the JSON doesn't include the ROUTE strings), a master language JSON file will be created using translation IDs, which will replace the master language strings in the _xml/JSON.

  • JSON translation files will be created for the other languages.

  • The translation files will be added to a new "project.i18n" directory for the survey.

  • The CAWI system will manage the translations - either at runtime (replacing strings as the questionnaire is run), or at install-time. But the user of the CAWI should not need to know the implementation details.

Example survey structure

├── cawi
│   ├── p2312opi002.dsc
│   ├── p2312opi002.ini
│   ├── p2312opi002.i18n
│   │   ├── p2312opi002.en.json
│   │   ├── p2312opi002.fr.json
│   │   ├── p2312opi002.de.json
│   │   ├── engine.en.json
│   │   ├── display.fr.json
│   │   └── ...
│   └── ... other files and directories containing project assets

The above example has three languages for the survey itself, plus it is overriding the default strings for one or more strings in the engine (for Engish) and one or more strings in the display (for French).

Developer notes

What this means for "cawi-app":

  • Each survey needs its own instance of i18next, to allow per-survey customisation of the core strings.
  • Each request then needs its own copy of that instance, to allow the setLanguage() function to operate (this is a limitation of i18next).