Appendix B: Formatting Standards for Scripts
Lessons for our Language Mentor software can be created by any person or organization. This page outlines a set of standards for lesson scripts. These scripts are used in the process of creating lessons, and can also be made available to the end users of the lessons.
These standards are:
- Required for lesson scripts created by The Language Collaborative.
- Optional for lesson scripts created by individuals or organizations other than The Language Collaborative. Use them, modify them, or ignore them as you see fit.
Table of Contents:
- General Instructions
- Header Section
- Chunk Sections
- Chunk Section Examples
- Chunk Text Punctuation
- Literal vs. Idiomatic Translations
- Role Lines
- An Example of Identifying Dialog Characters
- Formatting: All text in scripts should be plain, unformatted text. The reason for this is that these scripts will be published as plain text files so that our users can easily load them into all types of reader software.
- "Line" Defined: When used in this document, the term line refers to a unit of text that is unbroken by carriage returns. If such a line is displayed on a page as two or more lines due to auto-wrapping of text, it is still considered to be one line for the purposes of this document.
- Order of Contents: The sections below specify the way in which the contents of the script should be arranged. They do this in two ways:
- Through explicit directions: For example, if we say, "Place this line directly below the such-and-such line", these are explicit directions.
- Implicitly, by example: If no explicit directions are given, the contents specified should be arranged in the same order as shown by the directions below. For example, chunk sections are placed below the header section.
- Blank lines: Blank lines should only be inserted where specified.
- Native Language Title Line: Include a title line for the lesson's native language.
- Romanized Target Language Title Line:
- Target Language Title Line:
- Author(s) Line: A single line containing the name(s) of the author(s) of the script. This line should not include other information such as professional affiliations or URLs. (These may be provided in the lesson description file which, among other things, specifies the information that will be displayed in the Language Mentor's credits screen.)
- Version and Date Information: This line will be added or updated before the script is made available to the public. When initially creating a script the line should be a placeholder which says (without the quotes) "Version & Date".
- Native Language Line: This line should start with the words "Native Language:" (without the quotes). This should be followed by the ISO 639-3 Codes for the lesson's native language.
- Example: Native Language: cmn
- Target Language Line: This line should start with the words "Target Language:" (without the quotes). This should be followed by the ISO 639-3 Code for the lesson's target language.
- Example: Target Language: eng
- Roles Line: This line should start with the word "Roles:" (without the quotes). This should be followed by a list of the roles used in the script's "Role Lines". Role lines are explained here. Roles should be separated by colons. If the script does not have any roles specify "Default".
- Example: Roles: Default
- Example: Roles: A:B
- Example: Roles: A:B:Announcer
- Example: Roles: Aina:Douglas:Ginny:Huibo:Qiwei
- Example: Roles: Douglas McCarroll:Ginny Sandman:Ren Huibo:Xi Aina:Zhang Qiwei
- Note: The order in which the roles are listed doesn't matter.
- Note: Spaces, numbers and punctuation (except colons) can be used within role names.
- Note: Don't put spaces in front of or after the colons.
- Script Code Line: This line should start with "Script Code:" (without the quotes). This should be followed by a four-to-six-letter code consisting of the authors initials (2 characters) and 2-4 characters that are taken from the lesson's title. The code doesn't have to be unique (it is okay if other lessons exist that use the same code). This code will be used when naming the lesson's audio files, and is intended to serve as a reminder of which lesson the files belong to.
- Example: Script Code: dmsf
- Blank Line: Insert a single blank line below the above-specified lines.
Create one "chunk section" for each of your lesson's chunks. Each section should contain the following:
- Romanized target language text line: We include a romanized version of target language text for some languages. For example, for Mandarin Chinese the target language text consists of Chinese characters, and the romanized text consists of Pinyin.
- Target language text line: A single line containing the target language text of the chunk.
- Native language text line: A single line for the lesson's native language. These should be translations of the chunk's target language text.
- Notes line (optional): A line beginning with "Notes: " that explains something about the chunk. This should only be needed for a small percentage of chunks, except in lessons that contain unusually difficult material. These notes will typically be in the native language, though they may refer to, and quote, target language content.
- Blank line: Insert a single blank line at the bottom of each chunk section.
Chunk Section Examples
Example 1 - Target Language is English:
[Target language text - English - Chunk #1]
[Native language text - Mandarin Chinese - Characters]
[Native language text - Spanish]
[Native language text - Cantonese - Characters]
[Target language text - English - Chunk #2]
etc...
Example 2 - Target Language is Mandarin Chinese:
[Target language text - Mandarin Chinese - Characters - Chunk #1]
[Target language text - Mandarin Chinese - Pinyin]
[Native language text - English]
[Target language text - Mandarin Chinese - Characters - Chunk #2]
etc...
Chunk Text Punctuation
- If your script uses romanized target language text lines, the punctuation for each chunk's target language text line and romanized target language text line should be precisely the same, except that the target language text line should use punctuation that is standard for the target language and the romanized target language text line should use standard English punctuation.
- For example, when writing in Chinese characters we would use the standard period - " 。" - that is used by the Chinese when writing Chinese characters. The pinyin text line would use the standard English period, i.e. " . "
- Punctuation for a chunk's native language text line(s) in most cases won't correspond to that used in the chunk's target language lines because of the different syntaxes used in different languages. These lines should use the normal punctuation that is used in the native language(s).
- When a sentence is broken up into two or more chunks, all chunks except the final chunk should be ended with one space plus an ellipsis, like this: " ..."
- Exception: If the language for a target language text line or native language text line uses a different convention to express the idea that the line will be continued, this should be used instead. For example, when writing Chinese characters the convention is to use six periods, like this: "......"
If your script uses two or more characters you'll want to specify which of the characters is saying each chunk. In many cases a character will say several chunks in sequence before another character speaks. We do this using "role lines".
Role lines can also identify characters in your script who aren't part of a dialog. For example, your script could have an "Announcer" role who announces the name of each section of a script.
Here's how we create role lines:
- Before the first chunk section, and before each chunk where the character changes, insert a role line, then a blank line.
- The role line should consist of the role's name followed by a colon. If you prefer, you can use letters (e.g. A, B, C) to identify your characters, rather than names.
- All roles should be specified in the header section's "Roles" line. The Roles line is explained here.
An Example of Identifying Dialog Characters:
A:
#############
## Chunk Section #1
#############
#############
## Chunk Section #2
#############
B:
#############
## Chunk Section #3
#############
A:
#############
## Chunk Section #4
#############
etc...