Author: Carla Czilczer
Date: 12.12.2025
OpenSesame version: 4.0.24

---

README – Language Localiser Demo for Local and Online Experiments in OpenSesame

Overview

You have created an experiment with the open-source program OpenSesame. Now you want to run it with participants who speak a different language, or share it with international colleagues.

Hardcoding translations or maintaining separate experiment files for each language (e.g., experiment_v1_EN.osexp, experiment_v1_DE.osexp) is tedious, error-prone, and hard to maintain.

This repository provides templates for implementing a Language Localiser in OpenSesame for local and online expeirments. This system allows you to maintain a single experiment file while dynamically loading instructions and stimuli in the participant's preferred language.

Repository Structure

This repository is divided into two folders to support both desktop (local) and web-based (online) data collection. Choose the version that fits your deployment needs:

1. Local

• Target: Lab/Desktop experiments.
• Backend: xpyriment (Python).
• Configuration: Uses standard Excel .xlsx files.
• Key Features: Leverages Python for easy file reading and variable management.

2. Online

• Target: Web experiments (OSWeb).
• Backend: OSWeb (JavaScript).
• Configuration: Uses semicolon-delimited .csv files.
• Key Features: Optimized for the browser environment; includes JavaScript workarounds to handle dynamic text loading where standard Python scripts won't work.

How It Works

Instead of typing text directly into the OpenSesame experiment file (e.g., into a loop, sketchpad or feedback item), you use variables (e.g., [welcome_msg]) defined in dedicated files that are loaded within the experiment.

1. Define: You store all your text (e.g., instructions) in external files (local: .xlsx, online: .csv).
2. Select: At the start of the experiment, a language is selected (e.g., "English", "German").
3. Load: A script looks up the correct column in your .xlsx or .csv files based on the language code (ISO_code).
4. Display: OpenSesame automatically fills the variables with the text in the chosen language.

Why Use This Approach?

✅ Scalable: Add a new language simply by adding a column to .xlsx or .csv files—no changes to the experiment structure required.
✅ Clean: Keeps your experiment logic separate from your content.
✅ Robust: Reduces copy-paste errors and version control headaches.
✅ Flexible: Includes templates for both simple messages and complex instruction loops.

Getting Started

1. Clone or download this repository.
2. Navigate to the folder that matches your needs (Local or Online).
3. Read the specific README in that folder for detailed setup instructions and file requirements.
4. Open the .osexp file to see the implementation in action.

---

⚠ Future OpenSesame updates may require adjustments. Feel free to contribute!

Adapted from: Language Localisation Demo for PsychoPy by Marcos Moreno-Verdú.