diff --git a/docs/plugins/translate.md b/docs/plugins/translate.md
new file mode 100644
index 0000000000..619ba1fada
--- /dev/null
+++ b/docs/plugins/translate.md
@@ -0,0 +1,138 @@
+# 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.
+
+The first `jsPsychPluginTranslate` trial in the timeline will set up (initialize) the translations. After that trial runs, you can access the translations throughout the rest of the experiment.
+
+1. **Initialize translations with a `jsPsychPluginTranslate` trial.** This trial must include the translation resources and a default/initial language. It can prompt the participant to choose their language, or just set the language directly.
+
+2. **Use the translations during the experiment.** After initializing translations with a `jsPsychPluginTranslate` trial, you can use the `jsPsychPluginTranslate` [class methods](#class-methods) in other parts of your experiment to retrieve translated text from the translation resources, based on the current locale. You can also change and retrieve the current locale at any point after initialization.
+
+## 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.
+
+## Class Methods
+
+This plugin exposes these static methods on the `jsPsychPluginTranslate` class:
+
+* `t(key, options)` — access i18next translation directly.
+* `setLocale(locale)` — change language programmatically.
+* `language()` — returns current language.
+* `languages()` — returns supported languages.
+* `resolvedLanguage()` — returns resolved language from i18next.
+
+After the translations have been initialized with a `jsPsychPluginTranslate` trial, these methods can be used in the experiment code to retrieve a translated string (`t`), change the language (`setLocale`), and get the current language settings (`language`/`languages`/`resolvedLanguage`).
+
+!!! info
+ The `jsPsychPluginTranslate` methods must be called _after_ translations have been initialized with a `jsPsychPluginTranslate` trial, so they should be used inside a function, such as in a [dynamic parameter](../overview/dynamic-parameters/) or in an [event-related callback function](../overview/events/).
+
+## 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
+
+```
+
+Using the JavaScript file downloaded from a GitHub release dist archive:
+
+```js
+
+```
+
+Using NPM:
+
+```
+npm install @jspsych/plugin-translate
+```
+```js
+import jsPsychTranslate from '@jspsych/plugin-translate';
+```
+
+## Examples
+
+### Initialize translations and prompt the participant to choose a language
+
+This example will show the stimulus and a dropdown menu with all locale (language) options listed in the resources. The language names that correspond to the locale codes will be shown according to the 'language_name_locale' value (in this case, "English" for "en" and "German" for "de"). After the participant selects a language and clicks the next button, translations will be initialized and the language will be set to the participant's response.
+
+```javascript
+const init_user_set_language = {
+ type: jsPsychTranslate,
+ stimulus: "Please choose your language:
",
+ resources: {
+ en: { translation: { greeting: "Hello!" } },
+ de: { translation: { greeting: "Hallo!" } }
+ },
+ button_text: "Continue",
+ language_name_locale: "en"
+};
+```
+
+After this `init_user_set_language` trial runs, calling `jsPsychTranslate.t` with a key from the resources (e.g. "greeting") will return the translated string based on the locale set by the participant.
+
+```javascript
+const translated_greeting = {
+ type: jsPsychHtmlKeyboardResponse,
+ stimulus: () => jsPsychPluginTranslate.t("greeting")
+};
+```
+
+Note that this uses a dynamic parameter for the `stimulus` because `jsPsychTranslate.t` can only be called after the translations have been initialized with a `jsPsychPluginTranslate` trial.
+
+The `translated_greeting` trial will show "Hello!" as the stimulus if the participant selected English, or "Hallo!" if the participant selected German.
+
+### Initialize translations and set locale without prompt
+
+This example will intialize translations and set the language to German, without displaying anything to the participant.
+
+```javascript
+const init_set_language = {
+ type: jsPsychTranslate,
+ set_locale: "de",
+ resources: {
+ en: { translation: { greeting: "Hello!" } },
+ de: { translation: { greeting: "Hallo!" } }
+ }
+};
+```
+
+After this `init_set_language` trial runs, you can call `jsPsychTranslate.t` to retrive a translated string from the resources, based on the `set_locale` value. In this example the language is set to German, so the `translated_greeting` trial below would show "Hallo!" as the stimulus.
+
+```javascript
+const translated_greeting = {
+ type: jsPsychHtmlKeyboardResponse,
+ stimulus: () => jsPsychPluginTranslate.t("greeting")
+};
+```
+
+Note that this uses a dynamic parameter for the `stimulus` because `jsPsychTranslate.t` can only be called after the translations have been initialized with a `jsPsychPluginTranslate` trial.
+
+### After initialization, change the locale without user prompt
+
+The translation resources only need to be defined the first time you run the trial. After that, you can change the language during the experiment with a trial that just sets the `set_locale` value.
+
+```javascript
+const change_language = {
+ type: jsPsychTranslate,
+ set_locale: "es"
+};
+```
+
+After this `change_language` trial runs, any text that is retrieved using `jsPsychTranslate.t` will return the Spanish (es) translations.
diff --git a/examples/jspsych-translate.html b/examples/jspsych-translate.html
new file mode 100644
index 0000000000..5892eea8d7
--- /dev/null
+++ b/examples/jspsych-translate.html
@@ -0,0 +1,81 @@
+
+
+
+ jsPsychTranslate Example
+
+
+
+ ;
+};
+
+type LabeledResourceMap = Record;
+
+const i18instance = i18next.createInstance();
+
+const info = {
+ name: "plugin-translate",
+ version: version,
+ parameters: {
+ /**
+ * HTML content to display to participants when prompting them to select a language.
+ * Typically used to present instructions or context for language selection.
+ * Only shown if `set_locale` is not set.
+ */
+ stimulus: {
+ type: ParameterType.HTML_STRING,
+ default: null,
+ },
+ /**
+ * An object containing i18next-compatible language resources, organized by locale.
+ * If provided, it will be used to initialize or update the i18next translation instance.
+ * Must follow the shape: `{ en: { translation: {...} }, de: { translation: {...} } }`.
+ * Required if i18next has not already been initialized.
+ */
+ resources: {
+ type: ParameterType.OBJECT,
+ default: null,
+ } as const satisfies {
+ type: ParameterType.OBJECT;
+ default: LabeledResourceMap | null;
+ }, // probably unnecessary type safety here, but leaving in for now...
+ /**
+ * If provided, the plugin will automatically switch to this locale
+ * without displaying a language selection interface.
+ * Requires i18next to be already initialized or `resources` to be provided.
+ * Must be a valid BCP 47 locale string (e.g., "en", "de", "es").
+ */
+ set_locale: {
+ type: ParameterType.STRING,
+ default: null,
+ },
+ /**
+ * The label to display on the confirmation button used to proceed to the next trial
+ * after selecting a language. Only shown when prompting for language choice.
+ */
+ button_text: {
+ type: ParameterType.STRING,
+ default: "Next",
+ },
+ /**
+ * The locale to use when displaying language names in the dropdown.
+ * For example, using "de" will display "Englisch", "Deutsch", etc.
+ * Must be a valid locale code supported by `Intl.DisplayNames`.
+ */
+ language_name_locale: {
+ type: ParameterType.STRING,
+ default: "en",
+ },
+ },
+ data: {
+ /**
+ * The locale selected or set during the trial, e.g., "en", "de", "es".
+ * This reflects the final language used for translation at the end of the trial.
+ */
+ locale: {
+ type: ParameterType.STRING,
+ },
+ },
+ // When you run build on your plugin, citations will be generated here based on the information in the CITATION.cff file.
+ citations: "__CITATIONS__",
+};
+
+type Info = typeof info;
+
+/**
+ * **plugin-translate**
+ *
+ * initial draft of new jsPsych translation plugin
+ *
+ * @author Courtney B. Hilton
+ * @see {@link /plugin-translate/README.md}}
+ */
+class TranslatePlugin implements JsPsychPlugin {
+ static info = info;
+
+ constructor(private jsPsych: JsPsych) {}
+
+ ////////////////////
+ // PUBLIC METHODS //
+ ////////////////////
+
+ static t = (key: string, options?: TOptions): string => {
+ return i18instance.t(key, options);
+ };
+
+ static setLocale = async (lang: string) => {
+ await i18instance.changeLanguage(lang);
+ };
+
+ static addResources = (lang: string, resource: Resource[string]) => {
+ i18instance.addResourceBundle(lang, "translation", resource, true, true);
+ };
+
+ static language = () => {
+ return i18instance.language;
+ };
+
+ static languages = () => {
+ return i18instance.languages;
+ };
+
+ static resolvedLanguage = () => {
+ return i18instance.resolvedLanguage;
+ };
+
+ //////////////////////////
+ // DOM CREATION HELPERS //
+ //////////////////////////
+
+ private createStimulusGroup(): HTMLDivElement {
+ const containerEl = document.createElement("div");
+ containerEl.className = "jspsych-stimulus-group";
+ return containerEl;
+ }
+
+ private createStimulusElement(html: string): HTMLDivElement {
+ const stimulusEl = document.createElement("div");
+ stimulusEl.id = "jspsych-translate-stimulus";
+ stimulusEl.innerHTML = html;
+ return stimulusEl;
+ }
+
+ private createDropdown(resources: LabeledResourceMap, locale: string): HTMLSelectElement {
+ const displayLanguageNames = new Intl.DisplayNames([locale], {
+ type: "language",
+ });
+
+ const dropdownEl = document.createElement("select");
+ dropdownEl.style.fontSize = "14px";
+ dropdownEl.style.fontFamily = "Open Sans, Arial', sans-serif";
+ dropdownEl.style.padding = "4px";
+ dropdownEl.id = "jspsych-translate-dropdown";
+
+ Object.keys(resources).forEach((code) => {
+ const option = document.createElement("option");
+ option.value = code;
+ option.textContent = displayLanguageNames.of(code) ?? code;
+ dropdownEl.appendChild(option);
+ });
+
+ return dropdownEl;
+ }
+
+ private createResponseButton(label: string, onClick: () => void): HTMLButtonElement {
+ const buttonEl = document.createElement("button");
+ buttonEl.className = "jspsych-btn";
+ buttonEl.style.marginTop = "20px";
+ buttonEl.innerText = label;
+ buttonEl.addEventListener("click", onClick);
+ return buttonEl;
+ }
+
+ //////////////////////////
+ // OTHER HELPER METHODS //
+ /////////////////////////
+
+ private async endTrial(selectedLanguage: string): Promise {
+ // save data
+ const trial_data = {
+ locale: selectedLanguage,
+ };
+ // end trial
+ this.jsPsych.finishTrial(trial_data);
+ }
+
+ private async initLanguage(selectedLanguage: string, resources: Resource): Promise {
+ // init i18next with the chosen language
+ await i18instance.init({
+ lng: selectedLanguage,
+ debug: true,
+ resources: resources,
+ });
+
+ this.endTrial(selectedLanguage);
+ }
+
+ private async changeLanguage(selectedLanguage: string): Promise {
+ await i18instance.changeLanguage(selectedLanguage, (err, t) => {
+ if (err) return console.log("something went wrong loading", err);
+ t("key");
+ });
+
+ this.endTrial(selectedLanguage);
+ }
+
+ private showLanguagePrompt(
+ display_element: HTMLElement,
+ resources: LabeledResourceMap,
+ stimulus: string,
+ buttonText: string,
+ languageLocale: string
+ ) {
+ const stimulusGroupElement = this.createStimulusGroup();
+ display_element.appendChild(stimulusGroupElement);
+
+ const stimulusElement = this.createStimulusElement(stimulus);
+ stimulusGroupElement.appendChild(stimulusElement);
+
+ const dropdownElement = this.createDropdown(resources, languageLocale);
+ stimulusGroupElement.appendChild(dropdownElement);
+
+ const responseButton = this.createResponseButton(buttonText, () => {
+ const selectedLanguage = (dropdownElement as HTMLSelectElement).value;
+
+ if (i18instance.isInitialized) {
+ this.changeLanguage(selectedLanguage);
+ } else {
+ this.initLanguage(selectedLanguage, resources as Resource);
+ }
+ });
+
+ display_element.appendChild(responseButton);
+ }
+
+ ///////////////////////
+ // MAIN TRIAL METHOD //
+ //////////////////////
+
+ trial(display_element: HTMLElement, trial: TrialType) {
+ const resources = trial.resources as LabeledResourceMap | null;
+ const setLocale = trial.set_locale ?? null;
+ const stimulus = trial.stimulus ?? null;
+
+ // IF resources present: validate
+ if (resources !== null) {
+ Object.entries(resources).forEach(([code, value]) => {
+ if (!value.translation || typeof value.translation !== "object") {
+ throw new Error(`Missing or invalid 'translation' for language ${code}`);
+ }
+ });
+ }
+
+ // IF setLocale present: validate
+ if (setLocale !== null) {
+ // 1. check that code is a valid Intl.Locale
+ try {
+ new Intl.Locale(setLocale);
+ } catch {
+ throw new Error(`Invalid locale code format: '${setLocale}'`);
+ }
+
+ // 2. check against provided resources
+ if (resources !== null) {
+ if (!resources.hasOwnProperty(setLocale)) {
+ throw new Error(
+ `The provided set_locale '${setLocale}' does not exist in the supplied resources object.`
+ );
+ }
+ }
+
+ // 3. if already initialized, check against i18next store
+ else if (i18instance.isInitialized) {
+ if (!i18instance.hasResourceBundle(setLocale, "translation")) {
+ throw new Error(
+ `The provided set_locale '${setLocale}' does not exist in the i18next resource store.`
+ );
+ }
+ }
+
+ // 4. neither resources nor store available to validate against
+ else {
+ throw new Error(
+ `Cannot validate set_locale '${setLocale}' — no resources provided and i18next is not initialized.`
+ );
+ }
+ }
+
+ // IF i18next already initialisesd: only change the language
+ if (i18instance.isInitialized) {
+ if (setLocale !== null) {
+ this.changeLanguage(setLocale);
+ return;
+ } else if (stimulus !== null) {
+ this.showLanguagePrompt(
+ display_element,
+ resources!,
+ stimulus,
+ trial.button_text,
+ trial.language_name_locale
+ );
+ return;
+ } else {
+ throw new Error("i18next is initialized, but no set_locale or stimulus was provided.");
+ }
+ }
+
+ // IF i18next isn't initialised: initialise it
+ if (!i18instance.isInitialized) {
+ if (resources === null) {
+ throw new Error("i18next is not initialized and no resources were provided.");
+ }
+
+ if (setLocale !== null) {
+ this.initLanguage(setLocale, resources as Resource);
+ return;
+ }
+
+ if (stimulus !== null) {
+ this.showLanguagePrompt(
+ display_element,
+ resources,
+ stimulus,
+ trial.button_text,
+ trial.language_name_locale
+ );
+ return;
+ }
+
+ throw new Error(
+ "i18next is not initialized and no stimulus or set_locale provided to guide initialization."
+ );
+ }
+ }
+}
+
+export default TranslatePlugin;
diff --git a/packages/plugin-translate/tsconfig.json b/packages/plugin-translate/tsconfig.json
new file mode 100644
index 0000000000..fc11d795d1
--- /dev/null
+++ b/packages/plugin-translate/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "@jspsych/config/tsconfig.contrib.json",
+ "compilerOptions": {
+ "baseUrl": ".",
+ "resolveJsonModule": true
+ },
+ "include": ["src"]
+ }
+
\ No newline at end of file