Overview

Vocareum supports providing lab instructions (README files) in multiple languages. When multilingual instructions are configured, learners see a language selector dropdown in the instructions panel, allowing them to switch between available languages seamlessly.

This feature works across all Vocareum IDE types — Vocareum Notebook (Jupyter), VSCode, and the classic Editor IDE.

How It Works

When a learner opens a lab, Vocareum checks whether the part's assignment library contains instructions in multiple languages. If multilingual instructions are found, a language dropdown appears at the top of the instructions panel. The learner can select their preferred language, and the instructions update instantly. Their language preference is saved automatically and remembered across sessions.

Setting Up Multilingual Instructions

Step 1: Prepare Your README Files

Create a separate README file for each language you want to support. Vocareum supports the following file formats for instructions:

README.md (Markdown — recommended)
README.html or README.htm
README.pdf
README.txt or README.text
README (plain text, no extension)

Step 2: Organize Files in the Language Directory Structure

Place your README files inside a lang folder within the docs directory of the assignment library (asnlib). Each language gets its own subfolder named with the ISO 639-1 language code.

$ASNLIB/public/docs/
└── lang/
    ├── en/
    │   └── README.md
    ├── es/
    │   └── README.md
    ├── fr/
    │   └── README.md
    ├── zh-CN/
    │   └── README.md
    └── pt/
        └── README.md

Important: The folder names must use standard ISO 639-1 language codes (e.g., en for English, es for Spanish, fr for French, ja for Japanese). For regional variants, use codes like zh-CN (Simplified Chinese), zh-TW (Traditional Chinese), or en-us.

Step 3: Upload via the Vocareum File Manager

Navigate to your course and open the assignment's Teacher View
In the file manager, navigate to $ASNLIB/public/docs/
Create the lang directory, and inside it create a subfolder for each language (e.g., en, es, fr)
Upload the corresponding README file into each language folder

That's it! The next time a learner opens the lab, the language dropdown will automatically appear.

Learner Experience

When multilingual instructions are configured:

Language Dropdown — A dropdown selector appears at the top of the instructions panel showing all available languages. Each language is displayed as its code and full name (e.g., "ES - Spanish, Castilian", "FR - French", "ZH-CN - Chinese (Simplified)").
Instant Switching — Selecting a different language from the dropdown immediately loads the instructions in that language. There is no page reload required.
Preference Saved Automatically — The learner's language selection is remembered. When they return to the lab — or navigate to other parts in the same course — their preferred language is pre-selected.
Default Language — If a learner has not previously selected a language, Vocareum defaults to English (en). If en is not available but en-us is, Vocareum will automatically fall back to en-us.
Fallback Behavior — If a learner's previously saved language is no longer available (e.g., the instructor removed that language), the system falls back to the first available language.

Supported Languages

Vocareum supports all ISO 639-1 language codes (190+ languages). Some commonly used codes include:

Code	Language
`en`	English
`es`	Spanish
`fr`	French
`de`	German
`pt`	Portuguese
`ja`	Japanese
`ko`	Korean
`zh-CN`	Chinese (Simplified)
`zh-TW`	Chinese (Traditional)
`ar`	Arabic
`hi`	Hindi
`it`	Italian
`ru`	Russian
`tr`	Turkish
`vi`	Vietnamese
`th`	Thai
`id`	Indonesian
`nl`	Dutch
`pl`	Polish
`sv`	Swedish

For the full list, refer to the ISO 639-1 standard.

IDE-Specific Behavior

Vocareum Notebook (Jupyter) & VSCode (Container Labs)

Instructions open as a README tab within the IDE
The language dropdown appears inside the README tab header
Switching languages reloads the README content in the tab

Classic Editor IDE

Instructions appear in the left panel (instructions panel)
The language dropdown appears at the top-left corner of the instructions panel
The panel can be resized or collapsed using the divider

Container Lab IDE

Instructions appear in a dedicated README panel
The language dropdown appears in the panel header
Works identically for both full-screen README mode and side-panel mode

Best Practices

Keep content consistent across languages — Ensure that all language versions of your README cover the same topics, steps, and information. Only the language should differ, not the content structure.
Use the same file format across languages — If your English instructions are in README.md, use README.md for all other languages too. This ensures a consistent rendering experience.
Test all languages — After uploading, open the lab in Student View and verify each language loads correctly by switching through the dropdown.
Use standard language codes — Stick to ISO 639-1 codes for folder names. Vocareum will display the full language name automatically (e.g., a folder named es will show as "ES - Spanish, Castilian" in the dropdown).
Provide English as a baseline — Even if your primary audience speaks another language, including an en folder is recommended as it serves as the default fallback.

Frequently Asked Questions

Q: Do I need to change any part settings to enable multilingual instructions?

A: No. Simply placing README files in the correct lang/ directory structure is enough. Vocareum automatically detects the available languages and shows the dropdown.

Q: What happens if I have a README file in docs/ and also have language folders in docs/lang/?

A: If language folders exist under docs/lang/, Vocareum uses the multilingual setup and the language dropdown appears. The README directly inside docs/ is ignored in this case.

Q: Can different languages use different file formats (e.g., English in .md, Spanish in .html)?

A: Yes, each language folder is scanned independently. You can have README.md in the en folder and README.html in the es folder. However, for a consistent experience, using the same format is recommended.

Q: Is the learner's language preference shared across parts?

A: Yes. The language preference is saved at both the part level and the course level. When a learner selects a language in one part, that preference carries over to other parts in the same course (as long as those parts also have multilingual instructions available in that language).

Q: Can I add or remove languages after learners have already started the lab?

A: Yes. Adding a new language folder will make it appear in the dropdown on the next lab load. Removing a language folder will cause learners who had that language selected to automatically fall back to the first available language.

Multilingual Instructions for Learners in Vocareum Labs