{{indexmenu_n>55}}
====== Translating a Game with AI ======

The strings do not have to be typed into the "Translation" tab by hand: they can be handed to a chatbot (ChatGPT, Claude, Gemini) and the filled file loaded back. It is still a translation, not a copy of the game: one game, one set of codes, common statistics — the only thing that changes is who filled the //dst// column. How the localization itself works is described in [[en:authors_main:game_management:localization|Multilingual Game]].

<note important>The chatbot needs **three** things: which language to translate into, the string file of that language, and the game export for context. Without the export the bot translates paragraphs blind — it sees neither the level, nor the puzzle, nor what that word at the end of the sentence is — and breaks the game exactly where it is easiest to break.</note>

===== What to prepare =====

  * **The language.** Its name and two-letter code: //English, en//. The code has to be one of the translation languages chosen in the game settings.
  * **The string file** — ''game_<id>_<lang>.json''. Game editor → the **"Translation"** tab → pick the translation language → the **"Download strings for translation"** button. The file holds what a translator needs: the live strings of that language, the already translated ones filled in (they are the glossary and the tone), the rest with an empty ''dst''. Strings marked "do not translate" and the addresses of links and files are left out.\ {{ :authors_main:game_management:localization_ai_buttons_en.png |The file for translation: the whole thing or only the shown strings, and loading the finished one back}} The **"only the shown ones"** button next to it hands out the same file built from the strings the filter and the groups left on screen — that is how an addition is sent for translation instead of the whole game.
  * **The game export** — ''game_<id>.json''. Downloaded from the game page or via ''%%https://qeng.org/game_export.php?gid=<id>%%'' (see [[en:authors_main:admin_api:admin_json_export|Export to JSON]]). It is context and nothing but context: the bot does not have to send it back.

===== The prompt to copy =====

Send this as the first message, attaching both files and putting the language in place of ''<TARGET LANGUAGE>''.

<code>
You are a professional game localizer for the qeng.org quest engine.

I give you three things:
1. TARGET LANGUAGE: <TARGET LANGUAGE> (name and its two-letter code, e.g. "English / en").
2. The translation job file `game_<ID>_<lang>.json` - the strings to translate.
   This is the ONLY file you edit and return.
3. The game export file `game_<ID>.json` - the whole game, for context only.
   Never return it.

### 1. The job file - the file you fill in

{
  "translations": {
    "en": [
      { "src": "Original string as it appears in the game", "dst": "" },
      { "src": "Another original", "dst": "An already existing translation" }
    ]
  }
}

- Inside "translations" there is exactly one key: the two-letter code of the
  target language. Keep it as it is, do not add other languages.
- `src` is the original string. NEVER change it, not by one character: it is the
  key the engine matches a translation by, and an edited `src` silently loses it.
- `dst` is your translation. `""` means "not translated yet" - that is the work.
- A non-empty `dst` is an existing translation. Keep it unless it is wrong, and
  use those entries as the glossary for terminology and tone of the rest.
- Keep the same entries in the same order. Do not add, delete, merge or split
  them. Identical strings do not repeat: one string is translated once for the
  whole game and applies everywhere it occurs.
- The strings are separate paragraphs and short fields (game name, level name,
  sector name, hint label, answer format), not whole pages: each one has to work
  on its own, and you cannot move text between them.
- If a string must stay exactly as it is - a brand, a proper name, a Latin
  quotation, a word the player has to type - leave `dst` empty and add
  `"skip": true` to that entry: { "src": "...", "dst": "", "skip": true }.
  Do not "translate" it into a copy of the original.
- Output the complete file as valid JSON with the same structure and nothing
  else: no explanations, no comments, no markdown fences.

### 2. Special keywords inside a string - they must survive

**Placeholder markers `⟦N⟧` and `⟦/N⟧`** - mathematical white square brackets
U+27E6 / U+27E7, not ASCII ones. They stand for markup the translator must not
retype: bold, links, images, templates.

- `⟦1⟧text⟦/1⟧` is a pair: wrap the matching part of your translation in the
  same pair.
- `⟦2⟧` with no closing partner is a standalone element (an image, a line break,
  a template): put it once, where it belongs.
- Every marker of the source must appear in the translation exactly once, and a
  paired one must keep its closing marker. Do not invent numbers that are not in
  the source and do not drop any.
- Markers may be reordered - word order differs between languages - but pairs
  must nest, never cross: `⟦1⟧a⟦2⟧b⟦/2⟧⟦/1⟧` is valid,
  `⟦1⟧a⟦2⟧b⟦/1⟧c⟦/2⟧` is not.
- `⟦⟦` and `⟧⟧` are an escaped literal bracket the author typed. Keep them
  doubled.

**Substitutions** - the engine replaces them with live values when the page is
shown. They stay readable inside the sentence and you may move them where the
word order needs them, but the translation must carry exactly the same set,
spelled exactly the same way, and no others:

  !username!  !name!  !teamname!  !game_id!  !task_id!  !task_n!
  !bonus!  !task_bonus!  !api:...!  !api_data!
  !no_answer!  !any_answer!  !no_status!
  %allcodes%  %codes%  (both may carry an argument: `%allcodes Sector%`)
  %hide%  %offline%  %pay_button KEY%  [olymp]

and the template punctuation `{%`, `%}`, `}:{` - keep the same count of each.
Translating one of these, or changing its case or spacing, makes the engine
refuse the whole file on import.

**Answer codes are never translated.** The game keeps one set of codes for every
language. If a string contains a word the player has to type as an answer, keep
that word exactly as in the original and translate around it.

### 3. The game file - context only

`game_<ID>.json` is the whole game. Use it to see which level a string belongs
to, what the puzzle is about, who is speaking, and how a term is used elsewhere.
Never output it, and never translate a string that is not in the job file.

{
  "game":     { ... },  // game settings
  "tasks":    [ ... ],  // levels, in play order
  "gbonuses": [ ... ],  // bonuses spanning several levels
  "lines":    [ ... ],  // level orders
  "authors":  [ ... ],
  "translations": { ... }  // dictionaries already stored, by language
}

"game":
  "name"          - the game title (translatable)
  "description"   - the poster / announcement, HTML (translatable)
  "finish_text"   - the text shown after finishing (translatable)
  "html_header"   - HTML shown above every level (translatable)
  "lang"          - the language the game is written in, e.g. "ru".
                    Every `src` in the job file is in this language.
  "langs"         - a JSON string: the map "translation language" -> "language it
                    falls back to", "*" meaning every other language, e.g.
                    {"en":null,"uk":null,"*":"en"}
  "answer_prefix" - a prefix players type before an answer; not part of a code
  everything else (start_time, end_time, type, stat, kind, price, ...) is
  settings, not text

"tasks" - one entry per level:
{
  "task": {
    "number": 1,              // the level number in the game
    "tid": 52075,             // the author-facing level id
    "working_name": "...",    // the level name players see (translatable)
    "name": "...",            // the level name in the statistics (translatable)
    "task": "<p>...</p>",     // the level text, HTML (translatable)
    "answer": "...",          // the answer FORMAT shown above the input box
                              // (translatable) - a hint like "one word in
                              // Russian", never an answer itself
    "script": "...",          // the level's JavaScript - only gt('literal')
                              // calls inside it are translatable, everything
                              // else in the script stays as it is
    "surrender_code": "...",  // typed by players - never translated
    "max_time": 3600, "score": 0, "codes": 0, ...   // settings
  },
  "codes":   [ { "name": "Sector 1", "code": "answer, synonym" } ],
             // "name" is translatable; "code" holds the answers and their
             // synonyms, comma separated - NEVER translated
  "bonuses": [ { "code": "...", "time": 0,
                 "description": "<p>...</p>",  // the bonus task (translatable)
                 "hint": "..." } ],            // shown after solving it
  "hints":   [ { "info": "Hint 1",             // the label (translatable)
                 "hint": "<p>...</p>",         // the content (translatable)
                 "delay": 600, "penalty": 0 } ]
}

The level text is HTML and may contain templates like `{% match lang }:{ ... %}`
and `<script>` blocks. In the job file all of that is already gone or replaced
by `⟦N⟧` markers: you only ever see plain text plus markers and substitutions.
Never add HTML tags to a translation.

A fragment marked `translate="no"` in the HTML never becomes a string at all. If
a phrase you see in the game is missing from the job file, that is usually why,
and it is deliberate.

### 4. How to translate

- Translate into <TARGET LANGUAGE>, keeping the register of the original: quest
  text is usually informal and playful, settings-like strings are neutral.
- Keep roughly the same length: the text goes into the same layout, often on a
  phone screen.
- Keep terminology consistent across the whole file - the same term gets the
  same translation everywhere. Read the already filled `dst` entries first.
- Riddles and wordplay: if the puzzle depends on the letters or the sound of a
  word, keep that word and translate around it rather than solving the puzzle
  away.
- Numbers, proper names, URLs and file names stay as they are.
- A string that is nothing but a substitution or a marker is not translated:
  leave its `dst` empty.

Now translate the file into <TARGET LANGUAGE> and output the complete JSON.
</code>

===== Loading the result back =====

  - Save the bot's answer as a ''.json'' file.
  - Editor → the **"Translation"** tab → the same language → **"Load translations from file"**.
  - A report appears next to the button: **"Loaded: N, skipped: M"**. What was loaded sits in the draft — nothing has reached the server yet.\ {{ :authors_main:game_management:localization_ai_report_en.png?800 |The load report: how many strings landed and how many were skipped}}
  - Look through the changes in the save dialog — they are listed line by line there — and save.

The file lands in the draft silently and overwrites: it is the file of **this** game, which left empty and came back filled, and editing an existing translation is exactly what it was handed out for.

//Skipped// is normal. A string ends up in that count when:

  * ''dst'' is empty (and there is no ''skip'') — the bot did not translate it. An empty translation deletes nothing: a half-filled file means "this much is done so far", not "drop the rest".
  * the same translation is already there — that does not count as an edit;
  * the ''src'' no longer exists in the game — the bot touched it up, or the task was edited after the file was downloaded;
  * the language in the file is not the one being translated.

If the skipped count is suspiciously high, the bot has almost certainly rewritten the ''src'': ask again, telling it to return the source strings without a single change.

===== A large game =====

A game of several hundred paragraphs will not fit into one answer. Cut the array into chunks of 100–200 strings, repeating the wrapper — ''translations'' and the language code — in every chunk:

<code>
{ "translations": { "en": [ ...the first 150 strings... ] } }
</code>

The files are loaded one after another and add up: each writes only its own strings. The order of the chunks does not matter.

===== What to check afterwards =====

  * **Placeholders and substitutions.** If the bot broke one, the string is not saved: the editor highlights it, and an import refuses as a whole with //"the translation does not preserve the ⟦N⟧ placeholders or the substitutions of the original"//. That is not pedantry — such a pair would never have applied anyway, and the player would have got the base text.
  * **The codes.** Make sure code words inside the text came back untouched. An auto-translated code word breaks a game more quietly than anything else.
  * **Proofreading.** Turn on the "translated" group in the table and read it through: a machine goes wrong where you do not expect it — in jokes, in how it addresses the player, and in terms that mean something specific in this game.
  * **The game itself** — with an explicit language: ''%%https://qeng.org/game/1234/?lang=en%%''.