Repository navigation
locale reference
This page is the reference for how Wordplay's locale files are structured: what's in them, what the special syntax means, how the tutorial is organized, and how to format rich text. It's a companion to the localize guide, which walks through the process of contributing a translation. Start there; come here when you need to look something up.
If you're writing in a right-to-left language like Arabic, Hebrew, or Persian, read Writing in RTL languages at the bottom before you start — it will save you some confusion.
The files in a locale's sections folder hold the text that appears in the Wordplay interface. They are eight slices of one document — node.json holds everything under node, ui-page.json everything under ui.page, and so on — so a path like ui.dialog.share.header tells you both what the text is and which file it lives in. The sections below describe that one document; see Localize for which file each piece is in.
If you (can) hover over any of the terms in this file, you may see some description of what the text should contain — and a tag that indicates whether the value is plain text, rich markup, a Wordplay name, or an emotion identifier (see Tagging convention below). If a field is missing a description or a tag, we're still working on writing those.
You'll see different sections of this file:
-
glossaryincludes widely-used terms that aren't already defined by a concept. Each entry has aword(the localized term) and adefinition(a short, learner-facing explanation). Wordplay uses these as headers, and you can also reference a term elsewhere in your writing with@followed by its id. For example, type@codeand it renders your localized word (say, "código") and links to its glossary definition. This keeps terminology consistent everywhere and lets you change a word in one place rather than searching and replacing it. (Glossary terms share the@syntax with concept links — see Formatting below.) An entry may also haveforms: the other ways that word gets written in your language — plurals, other endings, or another word that means the same. A reference stops at the end of a word, so@parametersfinds nothing unlessparametersis listed as a form. Every language needs different forms, so nobody translates these for you and no other language's list is copied into yours; add them on the workspace's Glossary tab (see Localize), or leave them out if your language doesn't need any. -
tokenincludes descriptions of every kind of symbol in a Wordplay program. These appear when selecting a token in the Wordplay editor, and are also given to screen readers to read when selected. -
nodeincludes many things about all of the parts of a Wordplay program that exist.-
namesis one or more valid Wordplay names for the node; it appears in the documentation and in the editor and describes what kind of content it is, liketokendescriptions. -
descriptionmay be the same text, or if there's some way of describing an instance of content in more specific way, this is better. (For example, rather than describing a function as just "function", the description might be the name of the function). -
emotionis the default emotion that nodes are given when they appear in the interface to speak. This determines their animation and the screen reader description of their emotion. -
docis the documentation that appears for the node. It should thoroughly explain how to use the node, in a consistent voice for the node's emotion and personality. - Nodes that can be evaluated have a
startandfinish, which appear in the interface during step by step evaluation, and describe what the node is doing to start evaluation and finish it. Some nodes only have astart, becausefinishwould be redundant. Some nodes also have additional phrases for intermediate steps, which appear when the node is evaluating those intermediate steps while stepping. - Some nodes have additional descriptions for details they contain, like a list's "item". These appear in placeholders and autocomplete.
- Some nodes have a set of
conflictphrases. These are essentially error messages that appear when there is an inconsistency on that particular kind of program content. Each conflict'sprimarytext is written in the voice of the node on which the conflict occurs. If there is asecondaryphrase, it should be written in a generic voice, and generally be the opposite of the primary statement. This allows for the portrayal of a conflict between the two nodes. - Some nodes have a set of
exceptionphrases. These are shown when the node halts a program unexpectedly, usually due to a conflict. They are shown inside of program output. They should be phrased consistently with conflicts that create them, and in the voice of the node.
-
-
basisdescribes the basic data types in Wordplay, includingnamesanddoc, just as in thenodesection. They also includenamesanddocfor any functions and conversions that they have.
Important
Never repeat a name that English already gives. Wherever a names field lists what creators can type — names, everything under basis, and a few others — every Wordplay project already gets the English names for free. So if English calls something 💬 and you also list 💬, you've added nothing, and you've made it look to the next translator like a word waiting to be translated. Translate the words; leave symbols and emoji to English. ["💬", "Frase"] should just be ["Frase"]. The one exception is a name you haven't translated yet: leave ["🎨", "Color"] alone so the untranslated part stays visible. npm run locales warns about these, and npm run locales-fix removes them for you.
-
inputandoutputdescribes input streams available in Wordplay, including theirnames,doc, and anynamesanddocfor inputs that they take. -
uiare phrases that appear in tooltips, screen reader descriptions, and headers in the interface. These are the easiest to find. -
systemis the handful of strings that appear outside the running app, where there is no Wordplay around them to give them context: the message shown when JavaScript is off, the message shown when a browser is too old, the description of the sharing image, andappDescription, the one-line description a phone, tablet, or computer shows when someone installs Wordplay as an app. Along with yourwordplayglossary word,appDescriptionis built intostatic/manifests/<code>.webmanifest— see Localize for how those files are generated.
All strings in the locale file support a template syntax, which allows for a few kinds of dynamic behavior.
-
Unwritten. To indicate that the string has not yet been written, write an
"$?"at the beginning of it. This will help you keep track of what's not yet written. -
Revised. To indicate that the string was revised, meaning that other strings need to be re-translated with respect to other translations, write an
"$!"at the beginning of it. This will indicate that other locales may need to be revised. -
Machine translated. A
"$~"at the beginning marks text that came from a machine translation and still needs a fluent speaker to review it. -
Inputs. Some strings take inputs, as noted in their documentation. Inputs are always referred to by name, never by number: write
$followed by the input's name. For example, a string that takes anameinput can say"Hello, my name is $name", which generates"Hello, my name is Amy"at runtime. (Older locales used numbered inputs like$1; those are gone. Numbered placeholders slip past the verifier's checks and get mangled by the auto-translator, so never introduce one.) -
Counts. If a noun's form depends on a number, the input is declared as a count and written
$#count[…|…], with one arm per plural form your language has, in CLDR order (zero, one, two, few, many, other) filtered to the forms your language actually uses — two for English, one for Japanese, four for Polish, six for Arabic. Write"$#count[one value|many values]"rather than a bare$countnext to a noun, which would read "1 values". -
Terminology Remember the
glossaryfield above? To refer to a term, write@followed by its id (e.g.@code). For example,"To create a new @project, click here."renders the localized word forprojectand links to its glossary definition. Glossary terms share the@syntax with concept links (an@idresolves to a concept when the id is a concept's, otherwise to a glossary term), and like concepts the ids themselves are not translated. (Earlier locales used$termfor this; it is now@term, so$is only for inputs.) -
Conditions To conditionally select a string, use
??, followed by an input that is either a boolean or possibly undefined value, and true and false cases:-
"I received $value ?? [$value | nothing]"Would check the value of$valueand if it's true or not undefined, show the value of$value, and show the textnothingotherwise -
"I received $value ?? [$other ?? [$value | $other] | nothing]"Does the same, but also does a check on the value of$otherinside.
-
-
Escapes To use a reserved symbol, just use two of them. Hopefully these aren't too common in your writing...
"$$""[[""]]""||"
Important
Delete the $?, $!, or $~ prefix whenever you write a string by hand. Each of those marks the string as the tooling's to rewrite, and an unmarked string is never touched. If you write or improve the text but leave the prefix, your wording gets overwritten the next time translations run — and for $? and $! that happens on an ordinary translation pass, not just a full re-translation. This applies to the most common contribution of all: filling in a $? string. Translate the text, then delete the $?.
(The in-app workflow handles this for you; it only matters when you're editing the JSON files directly.)
Every translator-facing string field in the TypeScript type declarations (under src/locale/*.ts and each route's PageText.ts) carries a TSDoc comment with one of four tags. The tag determines which editor the in-app workspace shows, and a missing tag means the field is hidden from contributors entirely.
| Tag | When to use | Type alias |
|---|---|---|
[plain] |
a single label, tooltip, or aria description | string |
[formatted] |
rich markup rendered via <MarkupHTMLView>
|
FormattedText |
[name] |
a valid Wordplay identifier or list of names | NameText |
[emotion] |
an emotion identifier | string |
If you add a new locale field while contributing structural work, include both a description and a tag, for example:
/** [plain] Tooltip shown when the contributor hovers the publish button */
publishHint: string;After editing locale type declarations, run npm run create-schemas to regenerate the JSON schema that powers VS Code's autocomplete and the in-app workspace's editor selection.
The [language]-tutorial.json file refers exclusively to the structure of the tutorial. There is no template for this, as tutorials will likely reflect the structure of the English tutorial, which is about 20,000 words of English. Therefore, it's best to copy and paste it or another translation and start from it. You could write an entirely different play, and for some languages and cultures, that might make sense! That said, the structure, content, and sequence of the play was carefully constructed to teach the Wordplay programming language, so it's best to think carefully about how to deviate from its structure.
The tutorial is structured as a sequence of Acts, which are a sequence of Scenes, which are a sequence of Lines. Acts and scenes have a name, which appears on their introductory screens, as well as a performance, which is a Wordplay program to show on those introductory screens. Scenes also have an optional concept, which is one of the keys in the node, input, output, or basis sections in the locale file.
There are five kinds of performance commands, each of which are a list of strings, the first of which is the mode in which to show the program, and the remaining of which are lines of the program to show.
-
Output (fit)
["fit", "code", ... ]Program output is shown and fit to the window. Code is hidden. -
Output (fixed)
["fix", "code", ... ]Program output is shown, but not fit to the window. Code is hidden. -
Edit
["edit", "code", ... ]Both program output and code are shown. Output is fit. -
Conflict
["conflict", "code", ... ]Both program output and code are shown, and any conflicts in the code are intentional. This is important to note, since as you'll see below, we check tutorial programs for unintentional conflicts. -
Use
["use", "fit|fix|edit|edit|conflict", "name", "input1" ... "input-n" ]This special performance refers to predefined performances in Performances.ts. You might find that you want to reuse programs written in other translations, rather than copying them into a translation. In that case, you can move them toPerformances.tsand then everyone can reuse it. The programs inPerformances.tscan all optionally take inputs, allowing them to be customized to a language, so when using one, be sure to check what inputs it requires.
Finally, a scenes lines: this is a list of one of three kinds of things:
-
Pause
null, which represents a "pause" in a scene, which breaks up dialog into a separate screen. -
Dialog (e.g.,
["concept", "emotion", "dialog", ...]).- The first item in the list is the name of a
node,input,output, orbasisin the locale file, a how-to ID, or the special character names⊤/⊥(true / false). - The second item is an emotion. VS Code will autocomplete the allowed emotions (though let us know if you want to create a new one!).
- All remaining items are individual paragraphs that appear in a character's speech bubble. So if you want a new paragraph, add a separate string in the list. Note: all dialog is treated the same as
docfields in the locale, so you can format text in all the same ways, including rich text formatting, web links, concept links, and code examples. In localization mode you can edit these inline by clicking the speech bubble; the editor warns if any@Conceptlinks don't resolve.
- The first item in the list is the name of a
-
Performance Just like the performances in the
actsandscenes. The key difference, however, is that these persist: whatever performance is included as a line will be shown until a new performance is reached in the play.
All doc fields in the locale (and all dialog) can use the following formatting syntax:
| Format | Example |
|---|---|
| Bold | *I am bold* |
| Italic | /I am italic/ |
| Extra bold | ^I am extra bold^ |
| Underline | _I am underlined_ |
| Concept link |
I am a concept link to @Text. Concept names can refer to a node, input, output, or basis key (e.g. @FunctionDefinition), a UI key via @UI/..., one of the project view's interface tours via @Tour/... (stage, source, docs, palette, collaborate, project), a how-to via @HowTo/..., a Unicode codepoint via its hex (e.g. @1F4AC), or a character. Concept names themselves are not translated. |
| Glossary term |
I am a @value. A bare lowercase @id refers to a glossary term (from the glossary field), rendered as its localized word and linked to its definition. Ids are not translated. |
| Web link | I am a web link to <wordplay@https://wordplay.dev> |
| New paragraph | \n\n |
| Wordplay code | \1 + 1\ |
In the locale and tutorial files, you can also separate paragraphs by using an array of strings, where, each string is a paragraph: ["Paragraph one", "Paragraph two"].
Code that is alone in a paragraph shows its output. Code that is inline in a paragraph just shows the code. Create multiline code either by using \n in a string, or for better readability, as an array of strings, where each string is on a line: ["a: 'line one'", "b: a + 'line two'"].
If you're localizing Wordplay into Arabic, Hebrew, Persian, or any other right-to-left (RTL) language, there are some important things to know before you start writing. VSCode alongside other coding softwares are left-to-right (LTR) editors by default, which means it wasn't designed with RTL text in mind. This doesn't mean you can't use it, but it does mean you need to know what to expect and be careful about.
VSCode will automatically flip its text direction for you but in a confusing way. Here is what that means in practice:
- Cursor jumping at direction boundaries. VSCode does follow Arabic text direction when navigating with arrow keys, but when a line contains both Arabic and English (which is very common in UI strings), the cursor can jump or teleport unexpectedly at the point where the text switches direction. This is normal behavior. It's VSCode switching between RTL and LTR segments. It's also worth knowing that in bilingual bidi text, an English word embedded inside an RTL sentence is still read left to right for that word only. VSCode may not always respect this and can incorrectly flip the text that follows it, even though the surrounding Arabic should continue right to left.
- Mixed RTL/LTR strings. If you type an English word in the middle of an Arabic sentence, VSCode may scramble the visual order of the line. The text in the file itself is correct, but the editor displays it confusingly. Always verify mixed-direction strings in the browser preview, not by how they look in the editor.
- Copy-paste. Copying Arabic text from another app (a browser, Word, etc.) can silently embed invisible left-to-right markers into your string. These don't show up visually but can corrupt how the text renders. If something looks off after pasting, try retyping the text manually instead.
- No per-file direction setting. There is no built-in VSCode toggle to treat a single file as RTL. The editor will always display text LTR-first, so some things will simply look odd on screen even when they are correct.
Note If your text looks jumbled or reversed inside VSCode, take a deep breath, and open the browser preview before assuming something is broken. VSCode's LTR bias often misrepresents RTL strings visually, but the rendered output in Wordplay itself may be perfectly correct. Fixing something that only looks wrong in the editor is one of the most common RTL translation mistakes.
If you find VSCode's default RTL behavior too difficult to work with, there are extensions that can help. To find one:
- Open VSCode and click the Extensions icon in the left sidebar (or press
Ctrl+Shift+X/Cmd+Shift+X) - Search for Arabic or RTL in the search bar
- Look for an extension that adds RTL text direction support, such as Arabic Support or similar
- Click Install and reload VSCode when prompted
Alternatively, some contributors find it easier to draft their RTL translations in a native RTL app like Microsoft Word or Notepad, where bidi text behaves naturally, and then paste the finished strings into VSCode. If you do this, double-check for invisible bidi characters introduced during paste (see above).
- Always test your strings in the browser preview (
npm run dev) rather than relying on how they look in the editor - For strings that mix Arabic and English (such as a label containing a code keyword or brand name), check the rendered output carefully. These are the most likely to display incorrectly.
- If a string looks correct in the browser but wrong in VSCode, trust the browser
- Run
npm run localesregularly to catch any formatting or syntax issues introduced during RTL editing
Do you find something confusing on this page? Submit a workflow issue, so we can improve it! Every contribution counts.