[instruments] Multilingual instrument support

SQL/0000-00-00-schema.sql

@@ -271,6 +271,18 @@ CREATE TABLE `test_names` (
   CONSTRAINT `FK_test_names_1` FOREIGN KEY (`Sub_group`) REFERENCES `test_subgroups` (`ID`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
 
+CREATE TABLE `test_names_multilingual` (
+  `ID` int(10) unsigned NOT NULL AUTO_INCREMENT,
+  `Test_name` varchar(255) NOT NULL,
+  `Full_name` varchar(255) NOT NULL,
+  `LanguageID` int(10) unsigned NOT NULL,
+  PRIMARY KEY (`ID`),
+  KEY `FK_test_names_multilingual_1` (`Test_name`),
+  CONSTRAINT `FK_test_names_multilingual_1` FOREIGN KEY (`Test_name`) REFERENCES `test_names` (`Test_name`),
+  KEY `FK_test_names_multilingual_2` (`LanguageID`),
+  CONSTRAINT `FK_test_names_multilingual_2` FOREIGN KEY (`LanguageID`) REFERENCES `language` (`language_id`)
+) ENGINE=InnoDB AUTO_INCREMENT=7 DEFAULT CHARSET=utf8;
+
 CREATE TABLE `instrument_subtests` (
   `ID` int(11) NOT NULL auto_increment,
   `Test_name` varchar(255) NOT NULL default '',

SQL/New_patches/2025-01-06-multilingual_test_names.sql

@@ -0,0 +1,13 @@
+CREATE TABLE `test_names_multilingual` (
+	`ID` int(10) unsigned NOT NULL AUTO_INCREMENT,
+	`Test_name` varchar(255) NOT NULL,
+	`Full_name` varchar(255) NOT NULL,
+	`LanguageID` int(10) unsigned NOT NULL,
+	PRIMARY KEY (`ID`),
+	KEY `FK_test_names_multilingual_1` (`Test_name`),
+	CONSTRAINT `FK_test_names_multilingual_1` FOREIGN KEY (`Test_name`) REFERENCES `test_names` (`Test_name`),
+	KEY `FK_test_names_multilingual_2` (`LanguageID`),
+	CONSTRAINT `FK_test_names_multilingual_2` FOREIGN KEY (`LanguageID`) REFERENCES `language` (`language_id`)
+) ENGINE=InnoDB AUTO_INCREMENT=7 DEFAULT CHARSET=utf8
+
+UPDATE session SET LanguageID='1' WHERE LanguageID IS NULL;

modules/instrument_list/php/instrument_list.class.inc

@@ -225,7 +225,24 @@ class Instrument_List extends \NDB_Menu_Filter
 
                 $Ins = "instruments";
 
-                $ins = $instrument['Full_name'];
+                // Get multi-lingual full name if relevant / exists
+                $db = $this->loris->getDatabaseConnection();
+
+                $fullName = $db->pselectOne(
+                    "SELECT tn.Full_name
+                        FROM session s
+                        JOIN test_names_multilingual tn
+                            ON tn.LanguageID=s.LanguageID 
+                        WHERE tn.Test_name=:tn
+                        AND s.ID=:sid",
+                    [
+                        'tn'  => $instrument['Test_name'],
+                        'sid' => $_REQUEST['sessionID']
+                    ]
+                );
+
+                $ins = $fullName ?? $instrument['Full_name'];
+
                 $this->tpl_data[$Ins][$x][$i]['fullName'] = $ins;
 
                 $ins = $status->getDataEntryStatus();

modules/instruments/README.md

@@ -42,6 +42,11 @@ determines which candidate age is displayed as part of the
 metadata fields: `Candidate Age (Months)` or
 `Candidate Age at Death (Months)`.
 
+## Multi-lingual support
+Instrument labels are added in JSON files with the language code as a key. A default JSON labels file is included in `modules/instruments/language_labels/instrument_library_labels.json` which includes English and French for labels referenced in NDB_BVL_Instruments.class.inc. To add more languages to be supported by a project's instruments, first add the language to the `language` table. Next, copy the `instrument_library_labels.json` file to `project/instruments/language_labels/instrument_library_labels.json` with a new key for the additional language, and all of the same labels translated into the additional language. This new file should be tracked on the project's repository.
+
+Multilingual support is only available for PHP instrument at the moment. To have a multilingual instrument, the translated test name should be inserted into `test_names_multilingual` linked to the appropriate language ID. The function `$this->getLangLabel('key')` can be used anywhere in the instrument to display translated labels. A JSON file must be created in the same format as `modules/instruments/language_labels/instrument_library_labels.json` and put into the `project/instruments/language_labels/` directory with the following naming convention: <test_name>.json
+
 ## Interactions with LORIS
 
 The survey module uses instruments of the same format as data entry

modules/instruments/language_labels/instrument_library_labels.json

@@ -0,0 +1,52 @@
+{
+	"en-CA" : {
+		"age_out_of_range" : " (Age out of range)",
+		"data_entry_error_detected" : "A data entry error has been detected so this data <b>WAS NOT SAVED</b>",
+		"age_not_found" : "Candidate age could not be found.",
+		"date_of_administration" : "Date of Administration",
+		"candidate_age" : "Candidate Age (Months)",
+		"candidate_age_death" : "Candidate Age at Death (Months)",
+		"window_difference" : "Window Difference (+/- Days)",
+		"examiner" : "Examiner",
+		"date_of_administration_required" : "Date of Administration is required",
+		"examiner_required" : "Examiner is required",
+		"required" : "Required.",
+		"field_required" : "This field is required.",
+		"yes" : "Yes",
+		"no" : "No",
+		"not_answered" : "Not Answered",
+		"specify_or_select" : "You must specify or select from the drop-down",
+		"88_refused" : "88 Refused",
+		"99_do_not_know" : "99 Do not know",
+		"select_status_leave_blank" : "You are required to select a status if you want to leave this time blank.",
+		"dnk" : "DNK",
+		"refusal" : "Refusal",
+		"date_or_NA_required" : "A Date, or Not Answered is required.",
+		"must_be_numeric" : "Value must be numeric."
+	},
+	"fr-CA" : {
+		"age_out_of_range" : " (Âge hors limites)",
+		"data_entry_error_detected" : "Une erreur de saisie a été détectée, donc ces données <b>N'ONT PAS ÉTÉ ENREGISTRÉES</b>",
+		"age_not_found" : "L'âge du candidat n'a pas pu être trouvé.",
+		"date_of_administration" : "Date d'administration",
+		"candidate_age" : "Âge du candidat (en mois)",
+		"candidate_age_death" : "Âge du candidat au décès (en mois)",
+		"window_difference" : "Différence de fenêtre (+/- jours)",
+		"examiner" : "Examinateur",
+		"date_of_administration_required" : "La date d'administration est requise",
+		"examiner_required" : "L'examinateur est requis",
+		"required" : "Requis.",
+		"field_required" : "Ce champ est requis.",
+		"yes" : "Oui",
+		"no" : "Non",
+		"not_answered" : "Non répondu",
+		"specify_or_select" : "Vous devez spécifier ou sélectionner dans le menu déroulant",
+		"88_refused" : "88 Refusé",
+		"99_do_not_know" : "99 Ne sait pas",
+		"select_status_leave_blank" : "Vous devez sélectionner un statut si vous souhaitez laisser ce champ vide.",
+		"dnk" : "NSP",
+		"refusal" : "Refus",
+		"date_or_NA_required" : "Une date ou Non Répondu est requis.",
+		"must_be_numeric" : "La valeur doit être numérique."
+	}
+}