Category: Test Configuration Level: Intermediate Reading time: 20 minutes Updated: 2026-01-03

Custom Translations

Quick Summary: Add custom translations to PEBL tests in new languages or create variant instructions (e.g., speed vs. accuracy) within the same language.

What You'll Learn

What custom translations are and when to use them
Required JSON file format for translations
How to upload translation files
How to create and edit translations in the browser
Managing multiple translations and variants
Sharing translations with the PEBL community

Overview

Every PEBL test includes built-in translations for common languages (English, Spanish, French, German, etc.). The custom translation system allows you to:

Add new languages: Translate tests into languages not in the battery
Override existing translations: Replace battery translations with your own text
Create instruction variants: Multiple versions in the same language with different emphasis (e.g., "fast" for speed emphasis, "accurate" for accuracy emphasis)
Customize for populations: Adapt instructions for specific groups (children, elderly, clinical)

Custom translations are study-specific: Each study can have its own custom translations without affecting other researchers' studies.

When to Use Custom Translations

Add a New Language

Scenario: You're conducting research with Hungarian participants, but the Corsi Block test only has English, Spanish, and French translations.

Solution: Create a custom corsi.pbl-hu.json translation file with Hungarian text.

Override Battery Translation

Scenario: The built-in Spanish translation uses formal "usted" form, but your participants expect informal "tú" form.

Solution: Upload a custom stroop.pbl-es.json that overrides the battery's Spanish translation.

Create Instruction Variants

Scenario: You're running an experiment where some participants get speed instructions and others get accuracy instructions (both in English).

Solution: Create two custom English translations:

simon.pbl-en-fast.json - Emphasizes responding quickly
simon.pbl-en-accurate.json - Emphasizes responding accurately

Adapt for Special Populations

Scenario: Testing children aged 6-8, and the standard instructions use vocabulary that's too advanced.

Solution: Create tapping.pbl-en-child.json with simplified instructions and child-friendly language.

Understanding Translation File Structure

File Naming Convention

Translation files follow a strict naming pattern:

{test-name}.pbl-{language-code}.json
{test-name}.pbl-{language-code}-{variant}.json

Examples:

corsi.pbl-en.json - English (default)
corsi.pbl-es.json - Spanish
corsi.pbl-en-child.json - English (child variant)
stroop.pbl-fr-fast.json - French (fast variant)

Language codes must be 2-letter ISO 639-1 codes:

en - English
es - Spanish
fr - French
de - German
pt - Portuguese
zh - Chinese
ja - Japanese
it - Italian
nl - Dutch
hr - Croatian
lt - Lithuanian
hu - Hungarian
etc.

Variant names (optional):

Lowercase letters, numbers, hyphens
Examples: fast, slow, child, elderly, practice, test

JSON File Format

Translation files are JSON objects with KEY-VALUE pairs:

{
  "INSTRUCTION_1": "Welcome to the test. Press any key to begin.",
  "INSTRUCTION_2": "You will see a sequence of blocks light up.",
  "PRACTICE_LABEL": "Practice Round",
  "CONTINUE_PROMPT": "Press SPACE to continue",
  "CORRECT_FEEDBACK": "Correct!",
  "INCORRECT_FEEDBACK": "Incorrect",
  "THANK_YOU": "Thank you for participating!"
}

Important rules:

✅ Keys must be in UPPERCASE (e.g., INSTRUCTION_1, not instruction_1)
✅ Keys must exactly match what the test code uses
✅ Values can contain any Unicode text
✅ Use \n for line breaks within text
✅ Use \" to include quotes within text
✅ File must be valid JSON (use a validator if unsure)
❌ Do not add extra keys not used by the test (they'll be ignored)
❌ Do not remove keys the test expects (test may show empty text)

Special characters:

{
  "MULTILINE": "First line\nSecond line\nThird line",
  "WITH_QUOTES": "He said \"Hello\"",
  "WITH_APOSTROPHE": "Don't forget this",
  "UNICODE": "Ελληνικά, 日本語, العربية"
}

Method 1: Upload a JSON File

Step 1: Find Which Keys the Test Uses

Before creating a translation, you need to know which keys the test expects.

Option A: Copy an existing translation

Go to /battery/{test-name}/translations/
Download an existing translation (e.g., stroop.pbl-en.json)
Use it as a template

Option B: Check test documentation

Some tests document their translation keys in the test's about file or documentation.

Option C: View the battery source

Look at the test's source files in the battery to find gStrings.KEY_NAME references.

Step 2: Create Your JSON File

Using a text editor (VS Code, Notepad++, etc.):

Create a new file
Copy the structure from an existing translation
Translate all values to your target language
Save as {test-name}.pbl-{lang-code}.json

Example: Creating German translation for Corsi

{
  "FORWARD_INSTRUCTION": "Merken Sie sich die Reihenfolge, in der die Blöcke aufleuchten.",
  "BACKWARD_INSTRUCTION": "Merken Sie sich die Reihenfolge und geben Sie sie rückwärts ein.",
  "PRACTICE_LABEL": "Übung",
  "CLICK_PROMPT": "Klicken Sie auf die Blöcke in der richtigen Reihenfolge",
  "CORRECT": "Richtig",
  "INCORRECT": "Falsch",
  "COMPLETE": "Test abgeschlossen. Drücken Sie eine Taste."
}

Step 3: Validate JSON

Online validators:

https://jsonlint.com/
https://jsonformatter.curiousconcept.com/

Copy and paste your JSON to check for syntax errors.

Common errors:

Missing commas between entries
Extra comma after last entry
Unescaped quotes
Non-UTF-8 encoding

Step 4: Upload to Platform

Log in to the platform
Go to My Studies > Select your study
Click Manage Tests tab
Find the test you want to translate
Click ⚙️ Configure next to the test
In the language section, click 📁 Manage custom translations for {test}
Click 📤 Upload JSON File
Fill in the form:

Test: Select from dropdown (should be pre-selected)

Base Language: Select language code (e.g., de for German)
Variant (optional): Leave blank for default, or add variant name
Description (optional): Note about this translation
Translation File: Choose your JSON file

9. Click Upload Translation

What happens:

File is validated for correct JSON syntax
File size must be under 1 MB
Translation is stored in the database
Translation becomes immediately available for this study

Step 5: Select the Translation

After uploading:

Return to ⚙️ Configure for the test
In the Translation Language section at the top
Select your custom translation from the dropdown (marked with ⭐ Custom)
Click 💾 Save Language
Test with ▶ Try it out to verify

---

Method 2: Browser-Based Editor

The platform includes a web-based translation editor for creating and editing translations without downloading/uploading JSON files.

Creating a New Translation in the Editor

Go to Manage Tests > ⚙️ Configure > 📁 Manage custom translations
Click ✏️ Create in Editor
Fill in the form:

Language: Select or enter language code

Variant (optional): Add variant name if needed
Description (optional): Notes about this translation

4. Click Create Translation

The editor loads with all keys from the battery's default translation
Edit each value in the form fields
Click 💾 Save at the bottom when done

Editor features:

All translation keys pre-populated from the battery
Textarea fields for multiline text
Character counter for long strings
Auto-save on blur (leaving a field)
Preview button to see changes
Validation warnings for empty required keys

Editing an Existing Translation

Go to Manage custom translations
Find your translation in the list
Click ✏️ Edit
Modify any values
Click 💾 Save

Important: Changes are saved immediately to the database. There is no undo, so be careful when editing.

Managing Custom Translations

View All Custom Translations

Go to ⚙️ Configure for any test
Click 📁 Manage custom translations for {test}
See list of all custom translations for this test in this study

Translation display shows:

Language name and code (e.g., "⭐ Spanish (es)")
Upload date and author
Description (if provided)
File size
Warning if it overrides a battery translation

Download a Translation

Use this to:

Back up your translations
Share with colleagues
Edit in a text editor

Steps:

Go to Manage custom translations
Find your translation
Click 📥 Download
JSON file downloads to your computer

---

Delete a Translation

Steps:

Go to Manage custom translations
Find your translation
Click 🗑️ Delete
Confirm deletion

What happens:

Translation file is removed from the database
Test reverts to battery translation (if it exists)
If no battery translation exists, test may show untranslated keys
No effect on other studies using the same test

Share with PEBL Community

If you've created a high-quality translation, you can share it with the PEBL community:

Go to Manage custom translations
Find your translation
Click 🌍 Share with Community
Fill in the form:

Your name (for attribution)

Contact email
Notes about the translation

5. Agree to share under an open license

Click ✉️ Submit Translation

What happens:

Translation is sent to PEBL maintainers for review
After review, it may be added to the official PEBL battery
You'll be credited as the translator/author
Other researchers worldwide can use your translation

Creating Instruction Variants

Variants allow multiple versions of a test in the same language with different instructions.

Example: Speed vs. Accuracy Emphasis

Speed variant (simon.pbl-en-fast.json):

{
  "INSTRUCTION_1": "Respond as QUICKLY as possible. Speed is more important than accuracy!",
  "INSTRUCTION_2": "Press the button as FAST as you can when you see the stimulus.",
  "FEEDBACK": "TOO SLOW! Try to respond faster."
}

Accuracy variant (simon.pbl-en-accurate.json):

{
  "INSTRUCTION_1": "Respond as ACCURATELY as possible. Accuracy is more important than speed!",
  "INSTRUCTION_2": "Take your time and press the CORRECT button for each stimulus.",
  "FEEDBACK": "Incorrect. Please focus on accuracy."
}

How to Use Variants

Create both variant translation files
Upload both to your study
In Manage Tests, create two separate test entries:

Test 1: Use "fast" variant

Test 2: Use "accurate" variant

4. Assign different participant groups to different test URLs

Or use parameter variants with different active translations for each variant.

Common Translation Keys by Test Type

Different types of tests use different translation keys. Here are common patterns:

General Keys (Most Tests)

{
  "INSTRUCTION_1": "First instruction screen",
  "INSTRUCTION_2": "Second instruction screen",
  "PRACTICE_LABEL": "Practice Round",
  "CONTINUE": "Press any key to continue",
  "THANK_YOU": "Thank you for completing this test"
}

Memory Tests (Corsi, Digit Span, etc.)

{
  "FORWARD_INSTRUCTION": "Instructions for forward recall",
  "BACKWARD_INSTRUCTION": "Instructions for backward recall",
  "SEQUENCE_PROMPT": "Enter the sequence in order",
  "CORRECT_FEEDBACK": "Correct!",
  "INCORRECT_FEEDBACK": "Incorrect"
}

Attention Tests (Flanker, Stroop, etc.)

{
  "FIXATION_PROMPT": "Fixation cross instruction",
  "RESPONSE_PROMPT": "Press the key corresponding to...",
  "FEEDBACK_CORRECT": "Correct",
  "FEEDBACK_INCORRECT": "Incorrect",
  "FEEDBACK_TIMEOUT": "Too slow"
}

Executive Function (WCST, Tower, etc.)

{
  "RULE_INSTRUCTION": "Match cards by...",
  "FEEDBACK_MATCH": "Correct match",
  "FEEDBACK_NO_MATCH": "No match",
  "RULE_CHANGE": "Rule has changed"
}

Best Practices

1. Start with a Template

Always copy an existing translation file:

Ensures you have all required keys
Maintains correct structure
Reduces syntax errors

2. Use Professional Translators for Research

For published research:

Use native speakers or professional translators
Back-translate to verify accuracy
Pilot test with target population
Document translation methodology in your paper

3. Keep Instructions Clear

Use simple, direct language
Avoid idioms that don't translate well
Keep sentence structure consistent with original
Match the formality level of the target culture

4. Test Thoroughly

After creating a translation:

Run through the entire test yourself
Check all instruction screens
Verify timing isn't affected by text length
Test with native speakers if possible

5. Document Your Translations

Keep notes about:

Who translated it
Date created
Any special adaptations made
Population it's intended for

6. Use UTF-8 Encoding

Save your JSON files as UTF-8:

Supports all languages and special characters
Most text editors default to UTF-8
If you see weird characters (�), check encoding

7. Version Control

Keep backups of your translations:

Download JSON files periodically
Store in version control (Git)
Document changes between versions

Troubleshooting

Problem: "Invalid JSON" error on upload

Causes:

Syntax error in JSON file
Missing or extra commas
Unescaped special characters
Non-UTF-8 encoding

Solutions:

Copy content to https://jsonlint.com/
Fix any errors highlighted by the validator
Common fixes:

Add missing commas between entries

Remove comma after last entry
Escape quotes: \" instead of "
Escape backslashes: \\ instead of \

4. Re-save as UTF-8

Try uploading again

---

Problem: Translation not appearing in test

Causes:

Translation not selected in Configure page
Browser cache showing old version
Translation keys don't match what test expects

Solutions:

Go to ⚙️ Configure for the test
Verify your custom translation is selected in the Language dropdown
Click 💾 Save Language
Hard refresh test page (Ctrl+F5 or Cmd+Shift+R)
If still not working, check browser console (F12) for errors

---

Problem: Some text still in English

Causes:

Missing translation keys
Keys have wrong names
Keys have wrong capitalization

Solutions:

Download the battery's default translation for reference
Compare your keys with the battery's keys
Add any missing keys
Ensure keys are UPPERCASE
Re-upload and test

---

Problem: Text cut off or overlapping

Causes:

Translated text is much longer than original
Test layout assumes English text length
Font doesn't support characters

Solutions:

Try to shorten translations while keeping meaning
Use abbreviations where appropriate
Test with different screen sizes
Report layout issues to platform administrators
Some tests support custom font sizes in parameters

---

Problem: Special characters not displaying

Causes:

File not saved as UTF-8
Font doesn't include characters
Browser not rendering correctly

Solutions:

Re-save JSON file as UTF-8 (not ANSI or Latin-1)
Test in different browsers
Check if battery includes that language (may have font support)
For non-Latin scripts (Arabic, Chinese, etc.), verify the test supports them

---

Problem: Can't find which keys a test uses

Causes:

Test doesn't have translations in the battery
Custom test without translation documentation

Solutions:

Check if battery has ANY translation for this test:

Look in /battery/{test}/translations/

2. If found, download one and use it as a template

If not found, test may not support translations
For custom tests, ask the test author for translation keys
Advanced: Examine the .pbl source code for gStrings. references

---

Advanced: Translation Priority

When a test runs, translations are loaded in this priority order (first match wins):

Custom translation (exact match): test.pbl-{lang}-{variant}.json for this study
Custom translation (language only): test.pbl-{lang}.json for this study
Battery translation: /battery/{test}/translations/test.pbl-{lang}.json
Fallback to English: /battery/{test}/translations/test.pbl-en.json

Example:

Study language set to es-fast (Spanish with "fast" variant)
Platform checks: custom es-fast → custom es → battery es → battery en

This means:

Custom translations always override battery translations
Variants fall back to base language if variant doesn't exist
English is the ultimate fallback

Advanced: Translation in Test Chains

When using tests in chains:

Per-test translations:

Each test in a chain can have its own translation
Set translation in ⚙️ Configure for each test individually
Different tests can use different languages (if needed)

Consistency recommendation:

Use same language for all tests in a chain
Avoid switching languages mid-battery
Confuses participants

Examples

Example 1: Adding Hungarian Translation

Scenario: Corsi Block test needs Hungarian translation.

Steps:

Download English template: corsi.pbl-en.json
Create new file: corsi.pbl-hu.json
Translate all values:

{
  "FORWARD_INSTRUCTION": "Jegyezze meg a blokkok felvillanásának sorrendjét.",
  "BACKWARD_INSTRUCTION": "Jegyezze meg és fordított sorrendben adja meg.",
  "PRACTICE_LABEL": "Gyakorlás",
  "CLICK_PROMPT": "Kattintson a blokkokra a helyes sorrendben",
  "CORRECT": "Helyes",
  "INCORRECT": "Helytelen",
  "COMPLETE": "Teszt befejezve. Nyomjon meg egy billentyűt."
}

Upload to study
Select hu in language dropdown
Save and test

---

Example 2: Child-Friendly English

Scenario: Adapt Stroop instructions for 6-8 year olds.

Standard (stroop.pbl-en.json):

{
  "INSTRUCTION_1": "You will see words displayed in different colors.",
  "INSTRUCTION_2": "Press the key corresponding to the color of the text, not the word.",
  "RESPONSE_PROMPT": "Indicate the color (press corresponding key)"
}

Child version (stroop.pbl-en-child.json):

{
  "INSTRUCTION_1": "You will see color words like RED, BLUE, and GREEN!",
  "INSTRUCTION_2": "Press the button for the COLOR you see, not the word. If the word RED is in blue, press the blue button!",
  "RESPONSE_PROMPT": "What color do you see? Press the button!"
}

Upload both, use the child variant for your child participants.

Example 3: Speed vs. Accuracy Instructions

Scenario: Simon task with speed/accuracy manipulation.

Speed (simon.pbl-en-fast.json):

{
  "INSTRUCTION_1": "Respond as FAST as possible!",
  "INSTRUCTION_2": "SPEED is more important than accuracy. React quickly!",
  "FEEDBACK_CORRECT": "Good!",
  "FEEDBACK_INCORRECT": "Keep going fast!",
  "FEEDBACK_TIMEOUT": "TOO SLOW!"
}

Accuracy (simon.pbl-en-accurate.json):

{
  "INSTRUCTION_1": "Respond as ACCURATELY as possible.",
  "INSTRUCTION_2": "ACCURACY is more important than speed. Take your time!",
  "FEEDBACK_CORRECT": "Correct!",
  "FEEDBACK_INCORRECT": "Incorrect - be more careful!",
  "FEEDBACK_TIMEOUT": "Respond when ready"
}

Create two test configurations in your study, each using a different variant.

Custom Translations

What You'll Learn

Overview

When to Use Custom Translations

Add a New Language

Override Battery Translation

Create Instruction Variants

Adapt for Special Populations

Understanding Translation File Structure

File Naming Convention

JSON File Format

Method 1: Upload a JSON File

Step 1: Find Which Keys the Test Uses

Step 2: Create Your JSON File

Step 3: Validate JSON

Step 4: Upload to Platform

Step 5: Select the Translation

Method 2: Browser-Based Editor

Creating a New Translation in the Editor

Editing an Existing Translation

Managing Custom Translations

View All Custom Translations

Download a Translation

Delete a Translation

Share with PEBL Community

Creating Instruction Variants

Example: Speed vs. Accuracy Emphasis

How to Use Variants

Common Translation Keys by Test Type

General Keys (Most Tests)

Memory Tests (Corsi, Digit Span, etc.)

Attention Tests (Flanker, Stroop, etc.)

Executive Function (WCST, Tower, etc.)

Best Practices

1. Start with a Template

2. Use Professional Translators for Research

3. Keep Instructions Clear

4. Test Thoroughly

5. Document Your Translations

6. Use UTF-8 Encoding

7. Version Control

Troubleshooting

Problem: "Invalid JSON" error on upload

Problem: Translation not appearing in test

Problem: Some text still in English

Problem: Text cut off or overlapping

Problem: Special characters not displaying

Problem: Can't find which keys a test uses

Advanced: Translation Priority

Advanced: Translation in Test Chains

Examples

Example 1: Adding Hungarian Translation

Example 2: Child-Friendly English

Example 3: Speed vs. Accuracy Instructions

Related Topics

Related Topics