Skip to content

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

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.1 is the first alternative of the [count:] in g02, g02.3 the 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.CurrentLineId is the current line’s ID; each choice has choice.LineId. Use them for voice-over, analytics or your own localization system.
  • CurrentText, CurrentRichText (TextMeshPro-ready) and CurrentSpans all 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.
  • SetLineLookup takes 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 the speaker column, which matters for languages where verbs and adjectives agree with the speaker.
  • Leave notes. A // comment above a line reaches the translator in the comment column.
  • Speaker names and tags aren’t text. speaker:Guard, portrait:sad and 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.bruja fails on errors, and warns about every line without an ID.
  • bruja lines add before export, so no line is missed.
  • bruja lines import -f story.bruja -i <lang>.csv for every language; it exits with 1 on errors.
  • bruja lines export after writers change the script, then add the new rows to each language’s table. Rows are keyed by id, 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, never 1,5).

Edit this page