Localization
Bruja stories are localized without touching the script. Every line the player sees gets a stable ID, the lines go to translators as a spreadsheet (CSV), and the game loads a string table per language at runtime, switching language at any moment. This page is the whole workflow, for writers, localization producers and programmers.
Contents
- How it works
- 1. Give every line an ID
- 2. Export the lines
- 3. Translate the table
- 4. Check a string table
- 5. Play it in the game
- Voice-over
- Writing for localization
- In a build pipeline
- What isn’t localized yet
How it works
name = "Wren"
coins = 3
> @Guard: Halt! Who goes there? #line:g01
> @Guard: Ah, {name}. You have [count: coins | no coins | a coin | {coins} coins]. #line:g02
* Pay the toll #line:g03
> @Guard: <b>Thank you.</b> Move along. #line:g04
A #line: tag names a line, question or choice. The story text stays the source language; each
other language is a string table from IDs to text:
| id | text |
|---|---|
g01 |
Halte ! Qui va là ? |
g02 |
Ah, {0}. Vous avez {1}. |
g02.1 |
aucune pièce |
g02.2 |
une pièce |
g02.3 |
{0} pièces |
g03 |
Payer le péage |
g04 |
<b>Merci.</b> Circulez. |
- Each entry is a template.
{0},{1}… stand for the line’s{expressions}and[variations], in the order they’re written, so translators can move them anywhere in the sentence.{{and}}are literal braces. - Each alternative of a variation is its own entry:
g02.1is the first alternative of the[count:]ing02,g02.3the third. An alternative’s own{0}is its own expression (here{coins}). - Markup (
<b>,<color=…>,<pause=…>, your own tags) is part of the text, so translators keep it, move it, or adjust a pause for their language. - A line with no entry in the table, or an empty one, shows the original text. A half-finished language always plays.
- IDs are letters, digits,
-and_, unique across the story and every file it imports. Once a story uses any ID, lines without one get a warning, so new lines don’t slip through.
The game picks the table, the story picks the line, and the runtime fills in the values. Nothing else changes: the same choices, variables, saves and logic run in every language.
1. Give every line an ID
You don’t type IDs by hand. Either:
- in the web IDE, Localize → Add line IDs, or
- on the command line:
bruja lines add -f story.bruja. It adds an ID to every dialogue line, question and choice that doesn’t have one, in the story and in every file it imports, in place, keeping your line endings.
> The tide is rising. #line:7f3a1c
Generated IDs are random six-digit hex, so they never collide and never change when you reword or
move a line: every language’s text stays attached to its line through every rewrite. You can write your
own (#line:harbor_guard_03) if your studio has a naming scheme.
Keep the IDs when you edit. If you rewrite a line so much that its translations are wrong,
give it a new ID (delete the tag and run lines add again), and translators will see it as new.
2. Export the lines
bruja lines export -f story.bruja -o lines.csv
(or Localize → Export lines to a new tab in the web IDE, which makes a lines.csv tab). The CSV has one row
per entry, with a byte order mark so Excel and Google Sheets read it as UTF-8:
| Column | |
|---|---|
id |
the line ID, with .1, .2… for variation alternatives |
text |
the source text as a template, with markup |
speaker |
who says it (@Guard:), for tone and gender agreement |
file, line |
where it is in the source |
comment |
notes for the translator: the // comment lines right above the line in the script, and what each {0} stands for ({0} = name; {1} = one of g02.1–g02.3 (count)) |
Comments are how writers talk to translators. A comment above a line travels with it:
// Shouted from the top of the wall; he can't see who it is.
> @Guard: Halt! Who goes there? #line:g01
3. Translate the table
Make a copy of the CSV per language (fr.csv, de.csv, ja.csv) and translate the text
column. Only id and text are read back; the other columns can stay, be reordered or be
deleted, and you can add your own (status, reviewer, character limit). Quotes, commas and line
breaks inside a cell are fine (standard CSV quoting).
Rules for translators:
- Keep every
{0},{1}… that the original has. You may reorder them, and repeat one. - Keep markup tags balanced (
<b>…</b>). - Leave a cell empty to fall back to the original for that line.
- Don’t change
id.
Any language and script works: the text is Unicode throughout (Japanese, Arabic, Cyrillic, emoji). Right-to-left layout and fonts are up to your game’s text renderer.
4. Check a string table
bruja lines import -f story.bruja -i fr.csv
checks the table against the story without changing anything:
| Problem | |
|---|---|
| an ID the story doesn’t have, or an ID twice | error |
a {n} the original line doesn’t have |
error |
a {n} from the original that’s missing |
warning (sometimes intended) |
<b> and </b> (or another paired tag) that don’t match |
warning |
It ends with a count, like 42 of 45 lines localized; 3 not in the table (they'll show the original), and exits with 1 when there are errors, so it can gate a build.
5. Play it in the game
C# (any .NET game):
var story = new Story();
story.Start(program);
story.SetStringTable(StringTable.FromCsv(File.ReadAllText("fr.csv")));
story.SetStringTable(null); // back to the source language, any time
story.SetLineLookup(id => myLocalization.Get(id)); // or text from your own localization system
- Switching takes effect from the next line, so a language menu can change it mid-story.
story.CurrentLineIdis the current line’s ID; each choice haschoice.LineId. Use them for voice-over, analytics or your own localization system.CurrentText,CurrentRichText(TextMeshPro-ready) andCurrentSpansall give the localized line; markup in a string table works like markup in the story.- The table isn’t part of a save: after
LoadState, set the player’s language again. A save made in one language loads fine in another. SetLineLookuptakes any function from ID to text (null: the original line), so the lines can come from an existing localization tool (Unity Localization, I2, a database) instead of CSV.
Unity: put each language’s .csv in the project as a TextAsset. Set StoryRunner.localization
to the starting language, and call runner.SetLocalization(csv) (null or empty for the source
language) when the player changes it.
Web IDE: Localize in the top bar adds IDs and exports the lines; add a .csv tab per
language and pick it in Language above the player.
Share links carry the tables, and the player page has the same picker, so you can send a
translator a link to review their work in context.
Voice-over
A line’s ID is a natural name for its recording: vo/fr/g01.ogg. Read story.CurrentLineId
when a line is shown and play the matching clip. Because IDs survive rewording, recordings stay
attached when writers fix a typo; give a line a new ID when the change means it must be
re-recorded. The CSV’s speaker column groups the script by actor.
Writing for localization
- Whole sentences. Write
> You have {coins} coins., not a sentence assembled from pieces in code. Translators can only reorder what is inside one line. - Variations are fine. Each alternative is translated on its own, and the story still picks which one to show.
- Say who is talking.
@Name:fills thespeakercolumn, which matters for languages where verbs and adjectives agree with the speaker. - Leave notes. A
//comment above a line reaches the translator in thecommentcolumn. - Speaker names and tags aren’t text.
speaker:Guard,portrait:sadand your own tags are identifiers for the game; show localized names from the game’s own tables.
In a build pipeline
bruja check -f story.brujafails on errors, and warns about every line without an ID.bruja lines addbefore export, so no line is missed.bruja lines import -f story.bruja -i <lang>.csvfor every language; it exits with 1 on errors.bruja lines exportafter writers change the script, then add the new rows to each language’s table. Rows are keyed byid, so merging is a lookup in any spreadsheet tool, and existing translations stay attached to their lines.
What isn’t localized yet
Line IDs cover everything written as dialogue, questions and choices. Some text isn’t, today:
- Strings in code. A string value (
items = ["a lamp"],input("Your name?"), an argument to a game function) is code, not a line, so it has no ID. Keep player-facing text in lines, or pass an ID to the game and let it show the localized text. [and: …]and[or: …]join lists with English words (“a, b, and c”). Avoid them in lines you localize, or write the whole line as a template that doesn’t use the list.- Plural rules.
[count: n | zero | one | many]chooses with the English rule (0, 1, more), so languages with more plural forms (Russian, Polish, Arabic) can only translate the three alternatives, not add forms. - Numbers print the same in every language (
1.5, never1,5).