Task Localization

TAPS and PsyFlow make cross-cultural localization efficient by cleanly separating task logic from configuration and content. This modular design allows researchers to adapt paradigms across languages and cultural contexts without modifying the task code, promoting global accessibility, reproducibility, and reuse.

Why It Matters: Localization is essential for making psychological tasks globally accessible and inclusive. By adapting tasks to different languages and cultural contexts, researchers can extend their reach, maintain standardization across implementations, ensure reproducibility of results, and improve usability for diverse participant groups—including children, older adults, and individuals with limited literacy.

How It Works In a TAPS-compliant task, all participant-facing content is cleanly separated from the task logic and stored in the config.yaml file. Specifically, localization targets the subinfo_mapping section (for registration labels and messages) and the stimuli section (for all text or textbox content). This modular structure enables full language adaptation without modifying any core Python code.

1. Manual Adaptation (Quick and Easy)

The simplest way to localize your task is to manually translate the config/config.yaml file. This is ideal when you’re using LLMs interactively (e.g., ChatGPT, Gemini, DeepSeek, Claude).

Paste your YAML content directly into an LLM chat window, along with a clear instruction.

Here’s an example prompt:

Orignal config.yaml

To save space we just show the relevant content.

Then copy the translated YAML back into your project and save as a localized config file, e.g., config.ja.yaml.

Translated config.ja.yaml

To save space we just show the relevant content.

2. Programmatic Localization via API

For automated localization workflows, use the built-in LLMClient class. It supports Google Gemini and DeepSeek (OpenAI-compatible) providers.

It will translate:

  • subinfo_mapping labels

  • Any stimuli with type text or textbox

from psyflow.llm import LLMClient
client = LLMClient(provider="gemini", api_key="your-key", model="gemini-1.5-flash")
translated_config = client.translate_config(
    target_language="Japanese"
)
# This translates in-memory without saving to disk.

More details can be found in LLMs.

3. Important Notes on Task Localization

  1. Always review the auto-translated content. While LLM-based translation performs well in most cases, it’s strongly recommended to have a native speaker verify the accuracy and cultural appropriateness of the translated text.

  2. Leverage text-to-speech (TTS) for multilingual audio delivery.
    Since psyflow supports TTS conversion, you can automatically generate audio files from the translated text. This enables consistent and scalable voice presentation across languages—without requiring human recordings.

    If you plan to use voice content:

    1. Delete the original voice files in the assets/ folder.

    2. Regenerate the audio using a TTS voice that matches the target language.

    See Text-to-Voice for details on how to configure voices and view the list of supported options.