Feat: add plugin-translate

docs/plugins/translate.md

@@ -0,0 +1,86 @@
+# plugin-translate
+
+This plugin enables dynamic language selection during a jsPsych experiment using the i18next translation framework. It can either prompt participants to choose a language from a dropdown menu or automatically switch to a specified locale. Language resources can be supplied directly, and selected language data is saved for each trial. This plugin is useful for multi-language studies, international deployments, or experiments requiring runtime translation changes.
+
+## Parameters
+
+In addition to the [parameters available in all plugins](https://www.jspsych.org/latest/overview/plugins#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of `undefined` must be specified. Other parameters can be left unspecified if the default value is acceptable.
+
+| Parameter              | Type         | Default Value | Description                                                                                                                                                                                               |
+| ---------------------- | ------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `stimulus`             | HTML\_STRING | `null`        | HTML content shown to participants when selecting a language. Only displayed if `set_locale` is not set. Useful for presenting instructions or prompts.                                                   |
+| `resources`            | OBJECT       | `null`        | An object containing i18next-compatible language resources. Must be provided if i18next is not already initialized. Should be structured as `{ en: { translation: {...} }, de: { translation: {...} } }`. |
+| `set_locale`           | STRING       | `null`        | If provided, the plugin switches immediately to this locale without displaying a language selection interface. Must be a valid locale code.                                                               |
+| `button_text`          | STRING       | "Next"        | The label for the confirmation button shown when prompting for language selection.                                                                                                                        |
+| `language_name_locale` | STRING       | "en"          | The locale to use for displaying language names in the dropdown menu. For example, "de" would display "Deutsch", "Englisch", etc.                                                                         |
+
+## Data Generated
+
+In addition to the [default data collected by all plugins](https://www.jspsych.org/latest/overview/plugins#data-collected-by-all-plugins), this plugin collects the following data for each trial:
+
+| Name     | Type   | Value                                                                |
+| -------- | ------ | -------------------------------------------------------------------- |
+| `locale` | STRING | The locale selected or set during the trial, e.g., "en", "de", "es". |
+
+## Install
+
+Using the CDN-hosted JavaScript file:
+
+```js
+<script src="https://unpkg.com/@jspsych/plugin-translate@VERSION_HERE"></script>
+```
+
+Using the JavaScript file downloaded from a GitHub release dist archive:
+
+```js
+<script src="jspsych/plugin-translate.js"></script>
+```
+
+Using NPM:
+
+```
+npm install @jspsych/plugin-translate
+```
+```js
+import jsPsychTranslate from '@jspsych/plugin-translate';
+```
+
+## Examples
+
+### Prompt the participant to choose a language
+
+```javascript
+const trial = {
+  type: jsPsychTranslate,
+  stimulus: "<p>Please choose your language:</p>",
+  resources: {
+    en: { translation: { greeting: "Hello!" } },
+    de: { translation: { greeting: "Hallo!" } }
+  },
+  button_text: "Continue",
+  language_name_locale: "en"
+};
+```
+
+### Automatically set locale without user prompt
+
+```javascript
+const trial = {
+  type: jsPsychTranslate,
+  set_locale: "de",
+  resources: {
+    en: { translation: { greeting: "Hello!" } },
+    de: { translation: { greeting: "Hallo!" } }
+  }
+};
+```
+
+---
+
+This plugin also exposes these static methods:
+
+* `TranslatePlugin.t(key, options)` — access i18next translation directly.
+* `TranslatePlugin.setLocale(locale)` — change language programmatically.
+* `TranslatePlugin.language()` — returns current language.
+* `TranslatePlugin.languages()` — returns supported languages.
+* `TranslatePlugin.resolvedLanguage()` — returns resolved language from i18next.

examples/jspsych-translate.html

@@ -0,0 +1,81 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>jsPsychTranslate Example</title>
+    <script src="../packages/jspsych/dist/index.browser.js"></script>
+    <script src="../packages/plugin-translate/dist/index.browser.js"></script>
+    <script src="https://unpkg.com/@jspsych/[email protected]"></script>
+    <link rel="stylesheet" href="../packages/jspsych/css/jspsych.css" />
+  </head>
+  <body></body>
+  <script>
+    const jsPsych = initJsPsych({
+      on_finish: function () {
+        jsPsych.data.displayData();
+      },
+    });
+
+    // allow participant to choose the language
+    const chooseLanguage = {
+      type: jsPsychPluginTranslate,
+      stimulus: "<p>Please choose your language:</p>",
+      resources: {
+        en: { translation: { greeting: "Hello!" } },
+        de: { translation: { greeting: "Hallo!" } },
+        es: { translation: { greeting: "Hola!" } },
+      },
+      button_text: "Continue",
+      language_name_locale: "en",
+    };
+
+    const hello = {
+      type: jsPsychHtmlButtonResponse,
+      stimulus: () =>
+        `<p style="font-size:48px;">${jsPsychPluginTranslate.t(
+          "greeting"
+        )}</p>`,
+      choices: ["Next"],
+    };
+
+    const transition = {
+      type: jsPsychHtmlButtonResponse,
+      stimulus: "Now the text will silently change to Spanish.",
+      choices: ["Next"],
+    };
+
+    // silently set the language without notifying participant
+    const silentlySetLanguage = {
+      type: jsPsychPluginTranslate,
+      set_locale: "de",
+      resources: {
+        en: { translation: { greeting: "Hello!" } },
+        de: { translation: { greeting: "Hallo!" } },
+      },
+    };
+
+    // silently change the language without notifying participant
+    const silentlyChangeLanguage = {
+      type: jsPsychPluginTranslate,
+      set_locale: "es",
+    };
+
+    const hello_again = {
+      type: jsPsychHtmlButtonResponse,
+      stimulus: () =>
+        `<p style="font-size:48px;">${jsPsychPluginTranslate.t(
+          "greeting"
+        )}</p>`,
+      choices: ["Next"],
+    };
+
+    const timeline = [
+      chooseLanguage,
+      hello,
+      transition,
+      silentlyChangeLanguage,
+      hello_again,
+    ];
+
+    jsPsych.run(timeline);
+  </script>
+</html>

packages/plugin-translate/CITATION.cff

@@ -0,0 +1,41 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Courtney B. Hilton"  # Replace with last name
+  given-names: "Courtney B. Hilton"   # Replace with first name
+  name-particle: "Courtney B. Hilton" # Replace with name particle(s)
+  orcid: "https://orcid.org/0000-0000-0000-0000"  # Replace with ORCID
+# More  authors can be listed here in the same format as above
+contact:  # Contact person for this extension
+- family-names: "Courtney B. Hilton"
+  given-names: "Courtney B. Hilton"
+  email: "{email}"          # Replace with contact person's email
+  orcid: "https://orcid.org/0000-0000-0000-0000"  # Replace with contact person's ORCID
+title: "jsPsychPluginTranslate"
+version: 0.0.0
+doi: 10.5281/zenodo.1234    # Replace with DOI
+date-released: 2000-01-01
+url: "{softwareUrl}"        # Replace with URL to this extension
+
+# If you wish to cite a paper on this extension instead, you can use the following template:
+preferred-citation:
+  authors:
+  - family-names: "Courtney B. Hilton"
+    given-names: "Courtney B. Hilton"
+    name-particle: "Courtney B. Hilton"
+    orcid: "https://orcid.org/0000-0000-0000-0000"
+  # More authors can be listed here in the same format as above
+  date-published: 2023-05-11
+  doi: 10.21105/joss.12345 
+  issn: 1234-5678
+  issue: 01
+  journal: Journal for Open Source Software
+  publisher:
+    name: Open Journals
+  start: 0001
+  title: "{title}"
+  type: article               # Other options include: book, pamphlet, conference-paper...
+  url: "{linkToPublicationInJournal}"
+  volume: 1
+
+# More information on the preffered-citation CFF format can be found at https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files#citing-something-other-than-software

packages/plugin-translate/README.md

@@ -0,0 +1,39 @@
+# plugin-translate
+
+## Overview
+
+This plugin enables dynamic language selection during a jsPsych experiment using the i18next translation framework. It can either prompt participants to choose a language from a dropdown menu or automatically switch to a specified locale. Language resources can be supplied directly, and selected language data is saved for each trial. This plugin is useful for multi-language studies, international deployments, or experiments requiring runtime translation changes.
+
+## Loading
+
+Using the CDN-hosted JavaScript file:
+
+```js
+<script src="https://unpkg.com/@jspsych/plugin-translate@VERSION_HERE"></script>
+```
+
+Using the JavaScript file downloaded from a GitHub release dist archive:
+
+```js
+<script src="jspsych/plugin-translate.js"></script>
+```
+
+Using NPM:
+
+```
+npm install @jspsych/plugin-translate
+```
+```js
+import jsPsychTranslate from '@jspsych/plugin-translate';
+```
+## Compatibility
+
+`plugin-translate` requires jsPsych v8.0.0 or later.
+
+## Documentation
+
+See [documentation](/plugin-translate/README.md)
+
+## Author / Citation
+
+Courtney B. Hilton...

packages/plugin-translate/jest.config.cjs

@@ -0,0 +1 @@
+module.exports = require("@jspsych/config/jest").makePackageConfig(__dirname);