TyranoScript translation workflow: .ks scripts to an English build

Somebody hands you a novel game built in TyranoScript and asks for an English version. The first thing you find is that the text is not sitting in a tidy file waiting to be translated. It is interleaved with engine tags, spread across scenario files, macros, and images, and some of what a player reads is not text in the project at all.

TyranoScript is a Japanese novel-game engine built on web technology. A project is essentially an HTML application: scenario lives in plain-text files with a .ks extension, and the words a player reads sit on the same lines as the commands that display them. TyranoBuilder, the GUI tool built on the same engine, produces the same project shape, so most of what follows applies to both.

This article is about the workflow around that reality — finding every piece of player-facing text, leaning on the engine's own multilingual support instead of reinventing it, giving translators rules that keep the build running, and handling the layout problems that appear the moment Japanese becomes English.

Find every place text lives before you quote the job

The scenario files are the obvious part. Open one and you see prose lines, which are what the player reads, interleaved with instructions in square brackets that load backgrounds, play sound, wait for a click, or jump to a label. A translator needs the prose and needs to leave the brackets alone, which is easy to state and easy to get wrong at line four thousand.

The part that gets missed is player-facing text that lives inside the tags rather than between them. Choice labels, button captions, glossary entries, and any text passed to a command as a parameter are all read by the player but look like code to anyone skimming for prose, and to a naive extraction script that only takes untagged lines.

Then there is text that is not in the scenario at all. The title screen, the config screen, save and load slots, and confirmation dialogs come from the engine's own template files, which a developer often edits directly. Any custom HTML, CSS, or JavaScript the developer added carries its own strings. And a novel game usually has words drawn into images — the logo, chapter cards, UI buttons, sometimes whole event scenes with captions — which no text extraction will ever see.

Do this inventory before you agree to a schedule or a price, not after. The scenario word count is the number everyone reaches for, and on a novel game it is usually the honest majority of the work — but the image pass, the template screens, and the choices buried in tag parameters are the parts that turn a two-week job into a two-month one, and they are invisible if you only look at the .ks files. Walking the game once with a notepad, writing down every screen that shows words, and comparing that list against whatever your extraction produces is an hour that reliably saves a week.

• Scenario prose in the .ks files, including every branch and every route
• Text inside tag parameters: choices, buttons, links, glossary entries
• Macros, which are defined once with text inside and reused everywhere
• Title, config, save and load screens from the engine templates
• Custom JavaScript or HTML the developer added on top
• Words baked into images: logo, chapter titles, UI art, CG captions

Use the engine's multilingual support, and prove it on five lines

Recent versions of TyranoScript include official support for shipping more than one language: a way to pull translatable scenario text out, a place to keep the translated version alongside the original, and a way for the built game to select a language. Use it before you consider writing your own extraction script, because a homemade pipeline has to solve tag preservation, branch coverage, and re-import all over again.

The exact commands, file names, folder locations, and version requirements change between releases, so read the localization chapter of the official documentation for the version you are actually on rather than any secondhand walkthrough, including this one. What is worth deciding up front is not which menu to click but what you need the mechanism to do.

Before anyone translates anything, run a pilot: translate five lines, including one line with a choice and one line with an inline tag, take them all the way through export, translation, re-import, and a real build, and look at them on screen. A five-line pilot that fails costs you an afternoon. The same failure discovered after a thousand lines costs you the project's schedule.

• Which text does the extraction actually capture, and which of the places listed above does it skip
• What file format do you get, and can a translator work in it or does it need converting
• Does re-import round-trip cleanly, including lines with tags in the middle of a sentence
• How does the built game choose a language, and can a player change it mid-session
• What happens to a line that has no translation yet — does it fall back to the original or show nothing

Tags are code, so hand over a rule sheet with the text

Most broken TyranoScript translations are not translation problems. They are a translator retyping a bracket, deleting a click-wait marker because it looked like a typo, or translating the contents of a tag. None of that is carelessness — it happens because nobody told them which characters were load-bearing.

Write the rules down once and send them with every batch. The exact tag names come from the official tag reference, but the rules do not change: everything inside square brackets is machinery, the marker that sets a speaker name stays even though the name itself is translated, and tags keep their position relative to the sentence unless English word order genuinely forces a move — in which case the translator flags it instead of guessing.

Send a name list with the rule sheet as well. Novel games carry a large cast, nicknames, honorifics, place names, and invented terminology, and a translator working line by line through a branching script will otherwise make a reasonable but different choice for the same name in chapter one and chapter six. Agreeing the spellings and the honorific policy up front — before the first batch, not during review — costs an afternoon and removes the single most common category of rewrite requests on a novel game.

A short before-and-after example does more than a page of instructions, because it shows exactly which characters survive:

Before
#ミサキ
そんなの聞いてないよ。[l][r]
……どうして黙ってたの?[p]

After
#Misaki
You never told me that.[l][r]
...Why did you keep it from me?[p]

It is a browser underneath, so fonts and line breaks behave like CSS

Because TyranoScript renders through web technology, typography is a stylesheet problem rather than an engine setting. That is mostly good news: you can point the English build at a font chosen for Latin text instead of accepting whatever Latin glyphs a Japanese font happens to include, which are often an afterthought and look wrong at message-box size. If you are adding a European language beyond English, check accented characters specifically, since a Japanese font may cover them badly or not at all.

Hand-placed line breaks are the other predictable problem. Japanese scenario writers commonly break lines by hand so the message box looks balanced, and every one of those breaks is wrong for English. Decide a policy before translation starts: either strip the manual breaks in the English scenario and let the box wrap on its own, or accept that someone re-places every break per language after the text is final. Doing neither means the English build has sentences snapping in half mid-phrase.

Then check the box itself. English usually needs more lines to say the same thing, so the longest lines in the script — not the average ones — decide whether your message window is big enough. Test the worst offenders you can find, look at the backlog and choice buttons too, and re-check the typing speed, because text that felt paced in Japanese can feel slow when the same beat runs twice as many characters. If the original uses ruby annotations for readings, remember they carry nothing into English and the layout that reserved space for them can be reclaimed.

Test the built game, along every route

Previewing in the editor is not the same as running the packaged build, and a novel game is exactly the kind of project where the difference bites: asset paths, fonts, and language selection can all behave differently once the game is exported. Test the artifact you intend to distribute, on the platforms you intend to distribute it on.

Route coverage is the other trap. Untranslated Japanese hides in the branch nobody replays — a bad ending, an optional scene, a route that needs a flag from a previous playthrough. Keep a checklist of every route and every ending and tick them off with the translated build, or use the engine's jump-to-label facility to reach the hard ones deliberately rather than hoping you stumble into them.

Finally, check what happens across a language change. A save made in one language should load in the other, and any text stored in save data — a chosen name, a flag rendered as a word, a bookmark label — should not come back frozen in the language it was saved in. Look at the save and load screens themselves in both languages while you are there, since those are template screens and are among the most commonly forgotten in the whole project.