How to make an English version of your game, in the right order

この記事を日本語で読む

Reaching more players ·

Players have started asking whether there will be an English version, or you have noticed that most people who visit your store page cannot read the language your game is written in. So you decide to make one, and the obvious plan is to get the text translated and drop it in. That plan leaves out most of the work, and the order in which you do the rest decides how much of it you end up doing twice.

What follows is a map of that order, with a check that tells you when each step is finished. The numbers come from a small project I made up for this article: one short game about a lighthouse keeper and a postman, written once in Spanish and once in Japanese, with an English translation, run through a few short scripts. They describe that sample only, not games in general; the scripts are there so you can get your own numbers.

  • Put the store page into English. Finished when an English reader can tell what the game is, and you have decided what your English version will include.
  • Find every place the game keeps text. Finished when you have a list of locations, not a word count.
  • Make the game able to show English. Finished when a build can switch language and no on-screen text is still written into the code.
  • Translate from one table with context on every line. Finished when the translation is back and you still have an exact copy of what you sent.
  • Check the returned file with a script, then play it through. Finished when the script reports no problems and someone who reads English well has played to the end.
  • Keep both languages in step after release. Finished when each update begins with a list of what changed since the last translation.

Put the store page into English before you touch the game

The store page is the smallest piece of an English version and the only one that needs no change to your build: a short description, a longer one, and any words on your screenshots or capsule art. In the sample it is two lines. Translating it first is an experiment you can undo, and it tests the assumption the whole project rests on, that people who read English want this game, before you spend weeks on the rest.

How you add a second language to a store page differs between stores, so look up where the per-language text goes in your store's official help. If you sell on Steam, reading Steam wishlist data by country covers where those numbers live and how to compare before and after without reading too much into small ones. On any store, say plainly on the English page that the game itself is not in English yet, so nobody buys it expecting otherwise.

This is also the moment to decide what English version means for your game, because the answer sets how much of the later work you take on. Text only? Subtitles for spoken lines? Redrawn images with words in them? If you sell on Steam, what Steam's supported languages list promises explains why it pays to decide where your line is before you tick anything; confirm the current options in the Steamworks documentation.

Find every place the game keeps text, before you count a word

The natural first move is to count words to get a price, but a count only covers text you already know about, so start with a list of places. I wrote a script that walks the sample project and sorts what it finds by where the text lives. Here is its report for the Spanish version, rearranged into a table.

Two of the five places, the code and the images, are not files you can hand to a translator. The code search found four candidates, but players see only three; the fourth is a debug message, which is why the script calls them candidates and leaves the call to you. Two of the three are halves of one sentence, Quedan and turnos, glued around a number. The script cannot read pictures, so it only lists the four image files. A file name proves nothing, so open each one. Words drawn into an image get redrawn, not translated, so they go on a list of their own.

Places the sample did not have, but your game might:

  • Text typed straight into an engine's event, scene or map editor. It may not sit in any file you can open as text, so look up how your engine exports it in the engine's official documentation.
  • A bitmap font or interface skin with words drawn into it, such as a pre-rendered OK button.
  • Credits, error messages, achievement names on each platform, and any line the game shows only once.
  • Trailer subtitles and the words in store screenshots, which belong on the store page's list.
Inventory of the sample project (Spanish version)

where the text lives            files  strings  chars  words
dialogue (csv)                      1        7    282     62
UI strings (json)                   1        8     67     11
literals in code (candidates)       1        4     41      9
store page                          1        2    158     37
images (open each one)              4        -      -      -
total                                       21    548    119

code candidates: "Fin de la partida", "Quedan ", " turnos", "debug: lamp state"
images: bg_sea.png btn_start.png sign_lighthouse.png title_logo.png

chars = characters on screen; spaces, {placeholders} and line-break codes excluded

Make the game able to show English before anyone translates

This is where the job stops being translation. The industry calls the whole of it localization: translating the text, plus making the game display, fit and behave correctly in another language. Most of that second half can be done now, with no translation in hand, and doing it first means the translator works from a table that will not change shape later.

Start by moving every player-facing string out of the code into the same table as the rest, and rebuild split sentences as one string with a placeholder. Quedan, then the number, then turnos becomes Quedan {turns} turnos, and the English becomes {turns} turns left: the number moves to the front, which a translator given the two fragments could only manage by guessing that the first may be left empty. How to externalize hardcoded strings covers finding every literal and the order to move them in.

Then check whether English fits. I compared every row of the sample with its English translation, counting characters with spaces included.

  • In this sample English came out shorter overall, yet two buttons grew. A total that shrinks says nothing about a single box, so check the shortest strings on screen, not the average.
  • In the same sample's Japanese version the count grew far more: 2.69 times the characters on dialogue. Counting each Japanese character as two columns, per Unicode's East Asian Width property, the growth was 1.35 times. Your font may follow neither count, so neither replaces looking at the screen.
  • The ten characters matter if your font is a hand-made bitmap font holding only the glyphs your game already used: k and w appear nowhere in the sample's Spanish. Show a test line with every letter and punctuation mark before translation starts.
  • Plurals. The plural rules built into Node, which come from the Unicode CLDR data, give Spanish the forms one, many and other, and English one and other. If your game already picks carta or cartas by number, English slots into the same mechanism. The sample's Te han llegado {count} cartas does not, so its English, {count} letters came for you, is wrong for a single letter too. Japanese, Chinese and Korean get a single form in the same data, so a game written in one of them may never have needed this.
  • To prove the step is done, fill the English column with each source string in square brackets and switch the build to English. Anything on screen without brackets does not come from the table yet, whether it sits in the code or in an image.
Spanish source vs English translation, same 17 rows

              rows  Spanish chars  English chars  ratio
interface       10            102             73   0.72
dialogue         7            339            347   1.02

interface strings that got longer in English
  Ajustes   7  ->  Settings  8
  Sí        2  ->  Yes       3

characters the English uses that the Spanish never shows (10)
  ' G I L O W Y k w y

the same game with a Japanese source, dialogue only
  129 chars    ->  347 chars   ratio 2.69
  257 columns  ->  347 chars   ratio 1.35   (each Japanese character = 2 columns)

chars here: spaces included, a line-break code counts as one, {placeholders} excluded
(the inventory above leaves spaces and the line-break code out, which is why it shows 282 for the same dialogue)

Still checking translation files by eye?

Loclint scans your CSV/JSON localization files and flags broken placeholders, untranslated strings, and encoding risks in seconds.

Run your first check — freeFree for 500 strings checked a month · no credit card

Translate from one table, with context on every line

Now the translation itself. Send one table, not a folder of game files: a key, the source text, and a context column saying who speaks, where the text appears and what each placeholder becomes. In the sample, the postman's line carries a note that he is the speaker and that {count} is a number. A translator who sees only Te han llegado {count} cartas cannot tell whether it is a menu label or a line of dialogue, or how much room it has.

Preparing a localization kit lists the material that keeps a translator from guessing: screenshots, a glossary of names, notes on each character's voice, length limits. Settle two things before work starts, who holds the rights to the translation and how the translator is credited, and take contract and rights questions to a professional. Last, keep an exact copy of the table you send; the final step depends on it.

Who translates is your decision, and each choice asks something different of you:

  • You, if you write English well. You know the game best; the catch is that your own mistakes are the hardest for you to see, so have someone else read the result.
  • A friend or player who reads English as a first language. Agree in writing what they will do, by when, and how they will be credited.
  • A freelance translator. Ask for quotes against your own counted table; building a localization estimate from your own text shows how to count it so quotes can be compared.
  • Machine translation followed by a person's review. Whether the output is good enough for your game is something only a fluent reader playing it can tell you; no script in this article judges quality.

Check the returned file with a script, then play it through in English

A returned translation can be broken in ways you will not notice by reading it in a spreadsheet: a missing row, a renamed placeholder, a lost line break. Those are mechanical, so a script should find them. The one below compares the translated table with the table you sent, key by key. Run against a delivered file into which I planted four mistakes, it found all four; against the correct translation it reported none.

  • Depending on the engine, a missing row shows up as a raw key, an empty button or the source text. Here it is the Quit button.
  • {Item} with a capital I is a different name from {item}, which is what the code fills in; one changed letter is enough to break the match.
  • The lost line break changes how the keeper's two sentences sit in the text box. The script counts breaks; it cannot tell whether the new layout looks right.
  • Before trusting a zero, edit the two patterns marked in the script to match your engine's placeholder and line-break syntax. A misspelled column name stops the script with an error instead of a misleading count.
  • What no script sees is everything that needs a reader: a line that is correct English but wrong for the scene, a joke that no longer works, a label that fits the table but not the button. That takes someone fluent in English playing from start to finish and reporting each problem with a screenshot and its key. What localization QA (LQA) is describes how to run that pass.
// check.js
// Check a translation against the table you sent:
//   node check.js sent.csv ja translated.csv en
// List source rows added, edited or removed since you sent it:
//   node check.js sent.csv ja current.csv ja --changes
const fs = require("fs");
const [srcFile, srcCol, trFile, trCol, mode] = process.argv.slice(2);

function read(file, col) {
  const text = fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "");
  const rows = [];
  let row = [], f = "", q = false;
  for (let i = 0; i < text.length; i++) {
    const c = text[i];
    if (q) {
      if (c === '"' && text[i + 1] === '"') { f += '"'; i++; }
      else if (c === '"') q = false;
      else f += c;
    } else if (c === '"') q = true;
    else if (c === ",") { row.push(f); f = ""; }
    else if (c === "\n") { row.push(f.replace(/\r$/, "")); rows.push(row); row = []; f = ""; }
    else f += c;
  }
  if (f || row.length) { row.push(f); rows.push(row); }
  const head = rows.shift();
  const k = head.indexOf("key"), v = head.indexOf(col);
  if (k < 0 || v < 0) throw new Error(file + ": no 'key' or '" + col + "' column");
  return new Map(rows.filter((r) => r[k]).map((r) => [r[k], r[v] ?? ""]));
}

// Edit these two patterns to match your engine's placeholder and line-break syntax.
const PLACEHOLDER = /\{[^}]+\}/g;
const BREAK = /\\n/g;
const tokens = (s) => (s.match(PLACEHOLDER) ?? []).sort().join(" ");
const breaks = (s) => (s.match(BREAK) ?? []).length;

const src = read(srcFile, srcCol), tr = read(trFile, trCol);
if (mode === "--changes") {
  for (const [key, s] of tr) {
    if (!src.has(key)) console.log("added  ", key);
    else if (src.get(key) !== s) console.log("edited ", key);
  }
  for (const key of src.keys()) if (!tr.has(key)) console.log("removed", key);
  process.exit(0);
}
const problems = [];
for (const [key, s] of src) {
  if (!tr.has(key)) { problems.push(["missing row", key, ""]); continue; }
  const t = tr.get(key);
  if (!t.trim()) { problems.push(["empty", key, ""]); continue; }
  if (tokens(s) !== tokens(t)) problems.push(["placeholders", key, tokens(s) + " -> " + tokens(t)]);
  if (breaks(s) !== breaks(t)) problems.push(["line breaks", key, breaks(s) + " -> " + breaks(t)]);
}
for (const key of tr.keys()) if (!src.has(key)) problems.push(["not in source", key, ""]);
for (const p of problems) console.log(p[0].padEnd(14), p[1].padEnd(16), p[2]);
console.log(src.size + " source rows, " + tr.size + " translated rows, " +
  problems.length + " problems");

$ node check.js table-es.csv es en-delivered.csv en
missing row    menu.quit
placeholders   item.get         {item} -> {Item}
line breaks    dlg.keeper.03    1 -> 0
empty          dlg.post.03
17 source rows, 16 translated rows, 4 problems

After release, keep both languages in step

Updates do not only add lines; they can also rewrite old ones. I made a version 1.1 of the sample's Spanish table with three new rows and one of the keeper's lines reworded, then ran the ordinary check against the English I already had, and the changes mode against the table I had sent.

The ordinary check found the three new rows and missed the reworded one, because English for that key still exists and its placeholders still match. Only the comparison with the table you sent shows that the English now translates a sentence the game no longer contains.

  • Before each release, run the changes mode and send only those rows with their context (four of twenty here). Merge what comes back into your English table and run the ordinary check on the whole table (checked alone, the four returned rows report 16 problems; merged, zero). Then keep the full current source table as your new copy; a copy of just the four sent rows would list the other 16 as added next time.
  • Give text with a new meaning a new key. Reworded under an old key, it passes the ordinary check and the old English keeps appearing where the new meaning belongs; a new key shows up there as a missing row.
$ node check.js table-es-v1.1.csv es en.csv en
missing row    menu.credits
missing row    item.name.oil
missing row    dlg.keeper.05
20 source rows, 17 translated rows, 3 problems

$ node check.js table-es.csv es table-es-v1.1.csv es --changes
edited  dlg.keeper.02
added   menu.credits
added   item.name.oil
added   dlg.keeper.05

Ship your next update with every string checked

Upload a CSV/JSON file and Loclint checks every entry — placeholders, untranslated text, duplicate keys, length limits — and tracks regressions between runs.

Related articles