nrw10 - Add language option to requests

Author: EJMFarrow

api/README.md

@@ -64,8 +64,9 @@ The `POST /render` route is used to render a given question. It expects a JSON d
 - `questionDefinition`: The Moodle-XML-Export of a single STACK question. For all routes, the question does not need to be complete. The API will supply defaults
 for all fields so minimum required XML is `<quiz><question type="stack"></question></quiz>`. A YAML representation of the differences between the question and the defaults
 can also be used. (See [Diff Route](#diff-route).) Any non-empty YAML will do e.g. `name: YAML Question`.
-- `seed`: Seed to choose a question variant. Must be contained in the list of deployed variants. If  
+- `seed`: Seed to choose a question variant. Must be contained in the list of deployed variants. If
   no seed is provided, the first deployed variant is used.
+- `lang`: Optional language code used for STACK `[[lang]]` blocks and translated strings. If omitted, the `Accept-Language` HTTP header is used as before.
 - `renderInputs`: String. Response will include HTML renders of the inputs if value other than ''. The input divs will have the value added as a prefix to their name attribute.
 - `fullRender`: Array consisting of a string prefix for validation divs and a string prefix for feedback divs e.g. `['validationprefix','feedbackprefix']` (`renderInputs` must also be set.) Response `questionrender` and `questionsamplesolutiontext` will be the full HTML render of the question with the inputs inserted in the correct place, full plot URLs, placeholders replaced with HTML and iframes included. Iframes will still need to be registered on the front
 end to be displayed properly. (`stackjsvle.js->register_iframe()` using the first array entry for each iframe in the response as the iframeid.)
@@ -110,8 +111,9 @@ The following keys can be contained inside the input configuration options. The
 The `POST /grade` route is used to score a given input for a question. The route expects a JSON document in the post body, which must contain the following fields:
 
 - `questionDefinition`: The Moodle-XML-Export of a single STACK question.
-- `seed`: Seed to choose a question variant. Must be contained in the list of deployed variants. If  
+- `seed`: Seed to choose a question variant. Must be contained in the list of deployed variants. If
   no seed is provided, the first deployed variant is used.
+- `lang`: Optional language code used for STACK `[[lang]]` blocks and translated strings. If omitted, the `Accept-Language` HTTP header is used.
 - `answers`: A map from string to string, containing the answers.
 
 For input rendered as single fields, one entry inside the `answers` map, with the input name as key is expected. More complex input types use multiple entries, with the input name as a prefix, e.g. matrix inputs.
@@ -134,6 +136,7 @@ The `POST /validate` route is used to get validation feedback for a single input
 
 - `questionDefinition`: The Moodle-XML-Export of a single STACK question.
 - `inputName`: The name of the input to be validated.
+- `lang`: Optional language code used for STACK `[[lang]]` blocks and translated strings. If omitted, the `Accept-Language` HTTP header is used.
 - `answers`. A map from string to string, containing the answers.
 
 The validation route returns a string field `Validation` with the corresponding rendered output and an array of arrays `iframes` of arguments to create iframes to hold JS panels e.g. JSXGraph, GeoGebra.
@@ -155,8 +158,9 @@ The requested file is returned.
 The `POST /test` route is used to run a question's test cases.
 
 - `questionDefinition`: The Moodle-XML-Export of a single STACK question.
+- `lang`: Optional language code used for STACK `[[lang]]` blocks and translated strings. If omitted, the `Accept-Language` HTTP header is used.
 
-The grading route returns the following fields:
+The test route returns the following fields:
 
 - string: `name`: The name of the question.
 - string: `messages`: Question level error messages.
@@ -335,7 +339,7 @@ Any plots generated by stack during rendering or grading, as well as static imag
 
 ### Multi language content
 
-The API currently supports outputting German and English localization, both for internal messages and as part of multi-language questions. To control which language is selected the `Accept-Language` HTTP header is parsed. If not present, the default language is English.  Note, in order to add additional languages, you will need to
+The API currently supports outputting German and English localization, both for internal messages and as part of multi-language questions. To control which language is selected for render, grade, validate, and test requests, include the `lang` property in the JSON request body. If not present, the `Accept-Language` HTTP header is parsed as before. If neither is present, the default language is English. Note, in order to add additional languages, you will need to
 set `$CFG->supportedlanguages`. For development you will need to include the Moodle language pack directly inside the appropriate `/lang/??`. These will be downloaded
 automatically on production build.
 

api/controller/GradingController.php

@@ -44,6 +44,7 @@ class GradingController {
     public function __invoke(Request $request, Response $response, array $args): Response {
         // TO-DO: Validate.
         $data = $request->getParsedBody();
+        $language = current_language($data['lang'] ?? null);
 
         $question = StackQuestionLoader::loadxml($data["questionDefinition"])['question'];
 
@@ -65,8 +66,6 @@ public function __invoke(Request $request, Response $response, array $args): Res
         $translate->search = '/(<span(\s+lang="[a-zA-Z0-9_-]+"|\s+class="multilang")' .
                              '{2}\s*>.*?<\/span>)(\s*<span(\s+lang="[a-zA-Z0-9_-]+"' .
                              '|\s+class="multilang"){2}\s*>.*?<\/span>)+/is';
-        $language = current_language();
-
         // If an input explicitly allows empty answers, and the response data doesn't
         // contain a value for the input, set the input value to an empty string.
         foreach ($question->inputs as $name => $input) {

api/controller/RenderController.php

@@ -45,6 +45,7 @@ class RenderController {
     public function __invoke(Request $request, Response $response, array $args): Response {
         // TO-DO: Validate.
         $data = $request->getParsedBody();
+        $language = current_language($data['lang'] ?? null);
         $question = StackQuestionLoader::loadxml($data["questionDefinition"])['question'];
 
         StackSeedHelper::initialize_seed($question, $data["seed"]);
@@ -69,8 +70,6 @@ public function __invoke(Request $request, Response $response, array $args): Res
         $translate->search = '/(<span(\s+lang="[a-zA-Z0-9_-]+"|\s+class="multilang")' .
                              '{2}\s*>.*?<\/span>)(\s*<span(\s+lang="[a-zA-Z0-9_-]+"' .
                              '|\s+class="multilang"){2}\s*>.*?<\/span>)+/is';
-        $language = current_language();
-
         $renderresponse = new StackRenderResponse();
         $plots = [];
 

api/controller/TestController.php

@@ -47,6 +47,7 @@ class TestController {
     public function __invoke(Request $request, Response $response, array $args): Response {
         // TO-DO: Validate.
         $data = $request->getParsedBody();
+        current_language($data['lang'] ?? null);
 
         ['question' => $question, 'testcases' => $testcases] = StackQuestionLoader::loadxml($data["questionDefinition"], true);
         $question->castextprocessor = new \castext2_qa_processor(new \stack_outofcontext_process());

api/controller/ValidationController.php

@@ -42,6 +42,7 @@ class ValidationController {
     public function __invoke(Request $request, Response $response, array $args): Response {
         // TO-DO: Validate.
         $data = $request->getParsedBody();
+        $language = current_language($data['lang'] ?? null);
 
         $question = StackQuestionLoader::loadxml($data["questionDefinition"])['question'];
 
@@ -71,6 +72,13 @@ public function __invoke(Request $request, Response $response, array $args): Res
                 $data["inputName"],
                 null,
             );
+        $translate = new \stack_multilang();
+        // This is a hack, that restores the filter regex to the exact one used in moodle.
+        // The modifications done by the stack team prevent the filter funcitonality from working correctly.
+        $translate->search = '/(<span(\s+lang="[a-zA-Z0-9_-]+"|\s+class="multilang")' .
+                             '{2}\s*>.*?<\/span>)(\s*<span(\s+lang="[a-zA-Z0-9_-]+"' .
+                             '|\s+class="multilang"){2}\s*>.*?<\/span>)+/is';
+        $validationresponse->validation = $translate->filter($validationresponse->validation, $language);
 
         $validationresponse->iframes = StackIframeHolder::$iframes;
         $response->getBody()->write(json_encode($validationresponse));

api/emulation/Language.php

@@ -179,8 +179,11 @@ public static function get_next_parent_language($lang) {
      */
     public static function api_current_language($requestheader) {
         $locale = locale_parse($requestheader);
+        if (!is_array($locale) || empty($locale['language'])) {
+            return 'en';
+        }
         $languages = [];
-        $requestedlanguage = strtolower($locale['language']) ?? 'en';
+        $requestedlanguage = strtolower($locale['language']);
         $languages[] = $requestedlanguage;
         $requestedregion = null;
         if (!empty($locale['region'])) {

api/emulation/Localization.php

@@ -27,26 +27,41 @@
 require_once(__DIR__ . '/Language.php');
 
 // phpcs:ignore moodle.Commenting.MissingDocblock.Function
-function current_language() {
-    $requestheader = ($_SERVER['HTTP_ACCEPT_LANGUAGE']) ? $_SERVER['HTTP_ACCEPT_LANGUAGE'] : 'en';
-    static $language = ApiLanguage::api_current_language($requestheader);
+function current_language($requestlanguage = null) {
+    static $language = null;
+
+    if (!$language && $requestlanguage !== null) {
+        $requestlanguage = trim((string) $requestlanguage);
+        if ($requestlanguage) {
+            $language = ApiLanguage::api_current_language($requestlanguage);
+            return $language;
+        }
+    }
+
+    if ($language === null) {
+        $requestheader = isset($_SERVER['HTTP_ACCEPT_LANGUAGE']) ? $_SERVER['HTTP_ACCEPT_LANGUAGE'] : 'en';
+        $language = ApiLanguage::api_current_language($requestheader);
+    }
+
     return $language;
 }
 
 // phpcs:ignore moodle.Commenting.MissingDocblock.Function
 function get_string($identifier, $component, $a = null) {
-    static $userlanguage = current_language();
-
+    static $userlanguage = null;
     static $string = [];
-    switch ($userlanguage) {
-        case 'en':
-            if (empty($string)) {
+
+    if ($userlanguage === null) {
+        $userlanguage = current_language();
+    }
+
+    if (empty($string)) {
+        switch ($userlanguage) {
+            case 'en':
                 // Load en values as defaults.
                 include(__DIR__ . '/../../lang/en/qtype_stack.php');
-            }
-            break;
-        default:
-            if (empty($string)) {
+                break;
+            default:
                 $variant = $userlanguage;
                 $region = ApiLanguage::get_next_parent_language($variant);
                 $language = ApiLanguage::get_next_parent_language($region);
@@ -61,8 +76,8 @@ function get_string($identifier, $component, $a = null) {
                 if ($variant !== $region && is_file(__DIR__ . "/../../lang/{$variant}/qtype_stack.php")) {
                     include(__DIR__ . "/../../lang/{$variant}/qtype_stack.php");
                 }
-            }
-            break;
+                break;
+        }
     }
 
     $localization = $string[$identifier];

api/public/bulktest.php

@@ -88,6 +88,7 @@ function send(filepath, questionxml) {
         const url = window.location.origin + '/test';
         http.open("POST", url, true);
         http.setRequestHeader('Content-Type', 'application/json');
+        const requestLanguage = 'en';
 
         // Create nested <div>s with ids and titles representing the file structure in
         // preparation for displaying results.
@@ -218,7 +219,7 @@ function send(filepath, questionxml) {
             }
           }
         };
-        http.send(JSON.stringify({'questionDefinition': questionxml}));
+        http.send(JSON.stringify({'questionDefinition': questionxml, 'lang': requestLanguage}));
       }
 
       /**

api/public/stack.php

@@ -49,6 +49,7 @@ function collectData() {
           questionDefinition: yamlEditor.getDoc().getValue(),
           answers: collectAnswer(),
           seed: parseInt(document.getElementById('seed').value),
+          lang: document.getElementById('lang').value.trim(),
           renderInputs : inputPrefix,
           readOnly: document.getElementById('readOnly').checked,
         };
@@ -162,6 +163,7 @@ function render_directory($dirdetails) {
         <h2>Question XML</h2>
         <textarea id="xml" cols="100" rows="10"></textarea>
         <h2>Seed <input id="seed" type="number"></h2>
+        <h2>Language <input id="lang" type="text"></h2>
         <div>
           <input type="button" onclick="send(); diff();" class="btn btn-primary" value="Display Question"/>
           <input type="checkbox" id="readOnly" style="margin-left: 10px"/> Read Only

tests/api_language_test.php

@@ -73,6 +73,10 @@ public function test_lang(): void {
         $language = fake_api_language::api_current_language('en');
         $this->assertEquals('en', $language);
 
+        // No setting. Empty request language.
+        $language = fake_api_language::api_current_language('');
+        $this->assertEquals('en', $language);
+
         // No setting. Other.
         $language = fake_api_language::api_current_language('pt');
         $this->assertEquals('en', $language);
@@ -82,6 +86,11 @@ public function test_lang(): void {
         $language = fake_api_language::api_current_language('en_us');
         $this->assertEquals('en', $language);
 
+        // No wildcard. Hyphenated request language.
+        \set_config('supportedlanguages', 'en,de', 'qtype_stack');
+        $language = fake_api_language::api_current_language('de-DE');
+        $this->assertEquals('de', $language);
+
         // Wildcard. Basic language.
         \set_config('supportedlanguages', 'en,de,*', 'qtype_stack');
         $language = fake_api_language::api_current_language('pt');
@@ -106,5 +115,10 @@ public function test_lang(): void {
         \set_config('supportedlanguages', 'en,de,pt_br', 'qtype_stack');
         $language = fake_api_language::api_current_language('pt_br_wp');
         $this->assertEquals('pt_br', $language);
+
+        // Variant. Region only with hyphenated request language.
+        \set_config('supportedlanguages', 'en,de,pt_br', 'qtype_stack');
+        $language = fake_api_language::api_current_language('pt-BR-WP');
+        $this->assertEquals('pt_br', $language);
     }
 }