Ink Localisation Tool
Developer utility: export text strings from Ink files.
In spare time over the last few days I threw together a tool to make it easier to localise Ink files, or to associate voice lines with Ink lines. It’s free, you can download it to use on your projects.
This came from some work I did a while back which always slightly annoyed me as it was hacky and used regular expressions. I realised last week that I could just do the same thing using Ink’s own parser.
Anyway, here it is — I hope someone finds it useful!
TL;DR
I’ve written a command-line utility that:
- Gives each line of Ink text an ID tag, rewriting the ink files.
- Extracts all the text from the Ink files into an external list of IDs and text content, as CSV or JSON.
This lets you:
- Do lightweight localisation for an Ink project by using Ink (at runtime) for the flow, but fetching text content from a localised file.
- Use the IDs for other things, such as associating audio recordings with each line of text.
Overview
Inkle's Ink scripting language is a great flow language for stitching together narrative-based games.
But because it’s designed to mash small fragments of text together in a very flexible way, it’s not designed for localisation, or for associating lines of spoken audio to the source file.
However, many studios don’t use the more advanced text-manipulation features of Ink — they just use it for creating a flow of complete lines of text. It’s a great solution for titles that care about branching dialogue. This means there’s a problem — how do you translate each line? And how do you play the right audio for each line?
This tool takes a set of raw ink files, scans them for lines of text, and generates a localisation ID to associate with each line. It writes the ink files back out again with these IDs in the form of Ink tags at the end of each line.
This means that every line of meaningful text in the Ink file now has a unique ID attached, as a tag. That means you can use that ID for localisation or for triggering the correct audio.
The tool also optionally exports CSV or JSON files containing all the IDs and their associated text from all the Ink files it processed — which can then be used as a basis for localisation.
Each time the tool is run, it preserves the old IDs, just adding them to any newly appeared lines (and removing ones which no longer exist).
So for example, take this source file:
After the tool is run, the source file is rewritten like this:
It also creates an optional CSV file like so:
And an optional JSON file like so:
Use in Development
Develop your Ink as normal! Treat that as the ‘master copy’ of your game, the source of truth for the flow and your primary language content.
Use this LocaliserTool to add IDs to your Ink file and to extract a file of the content. Get that file localised/translated as you need for your title. Remember that you can re-run LocaliserTool every time you alter your Ink files and everything will be updated.
At runtime, load your Ink content, and also load the appropriate JSON or CSV (which should depend on your localisation).
Use your Ink flow as normal, but when you progress the story instead of asking Ink for the text content at the current line or option, ask for the list of tags!
Look for any tag starting with #id:, parse the ID from that tag yourself, and ask your CSV or JSON file for the actual string. You can use the same ID to trigger an appropriate voice line, if you’ve recorded one.
In other words — during runtime, just use Ink for logic, not for content. Grab the tags from Ink, and use your external text file (or WAV filenames!) as appropriate for the relevant language
Further Reading
For more information, check out the Github page. This is released under MIT License, so use it for anything you want to!
Huge thanks to Inkle for Ink, and to Joseph Humphrey in particular. This utility uses Ink’s own parser to do the hard part of the processing.
