Audamir

part 36

Three thousand eight hundred keys and eighty-one files: texts as trees

In two days 3,839 translation keys were split into nine packages, rewritten as alphabetical trees and given the path of their package. What is done and what is not.

· 14 min read

Until 30 October 2026 the translations of the game Audamir lay in nine big files, one per language, and a new game in a realm could require a change of the core even when the core did not need it. From 31 October to 1 November, that is two days, this changed in five steps. It turned out that today there are 3,839 keys in 81 files in the folders of nine packages; each key begins with the path of its package, each file is a tree, and the names in each group go in alphabetical order. According to the evidence in the documents of the game, not one text changed, but the core still knows Kastgard (94 edges in 21 files), and a new realm still asks for a line in the table of the core.

Where it started: nine files and one core

On 30 October 2026 I was trying to find out why a new game in a realm forces a change of the core, even though the game "needs no change in core" (docs/I18N-SPLIT.md; the documents of the game are in English). The analysis of that evening measured:

  • Files: nine catalogues, 3,727 keys, 3,024,062 bytes in all, one line per key.
  • Cost of one game: the commit that added Lines added 42 lines to each of the nine catalogues of the core (378 lines, 40 keys). Of these, 31 were its own and 9 were read by the core.
  • Who writes the keys: the core 1,965 keys (52.7 %), Stacks 1,094 (29.4 %), Campaign 595 (16.0 %), Taflgard (today Rokgard) and its two games 73 (2.0 %).

The recommendation of the analysis was different from what was built: leave the keys unchanged and the lines flat. The decision of 31 October was the opposite; DESIGN §98 quotes the author: "so that the owner stays unambiguous for the future". So a key carries the path of its package: core.settings.size.values.small.label, kastgard.stacks.presets.classic.label, rokgard.colony.rule_move. One rule decides the owner: a key belongs to the lowest package that all the files which write it are allowed to read, otherwise to the core. The game must not read the texts of another game (except the game it builds on) or of its own realm, and the core reads the text of no package; it asks for it from the manifest, which names the key as data.

Five steps in two days

The versions come from the commits, Version ….

StepWhatNumbers
S1, §98the manager I18n.add, the guard, a pilot on Taflgard124 keys in 27 files
S2, §112, version 0.70.6the tree, the renaming, the split of Kastgard and the core3,665 keys, 4,652 literals in 145 files, 32,985 lines
template 1, §113, version 0.70.9Rokgard, Vitgard, Telgard, Colony, Lines52 renamings
alphabet, §114, version 0.70.10the order of the names in each group81 files
template 2, §115, version 0.70.18Kastgard36 renamings

Between S1 and S2 the renaming of Taflgard to Rokgard took place. Thanks to the path in the key, two commands were enough: node tools/i18n-rename.js --prefix taflgard rokgard rk produced 125 lines of the map, and --map … --step rk --write renamed 169 literals in 15 files and 1,116 lines in 36 catalogue files (DESIGN §102). The map docs/I18N-RENAMES.tsv today has 4,041 lines: S1 124, rk 125, S2 3,665, and two steps of the home screen, H5b 20 and H6 107 (keys that moved with the code into the package of Kastgard).

This is how the English file of the realm Rokgard looks today (texts shortened):

rokgard: {
  realm: {
    coin: 'Golden tokens',
    genre: 'Board games',
    hero_note: 'Your hero is the token, …',
    name: 'Rokgard',
  },
  restart_what_chains: 'The game starts from the beginning …',
  restart_what_colony: 'The game starts from the beginning …',
},

The whole key cannot be found in the tree with grep, so there is node tools/i18n.js --where KEY: it prints the file that writes the key, the owner by the rule, and the line in each of the nine languages.

Who has how many keys

Counts come from the text manager (I18n.owners) after loading the English catalogue, 1 November 2026:

PackageKeysShareCode filesText files
core1,70044.3 %(the core has 102 files)9
kastgard1403.6 %59
kastgard/stacks93424.3 %679
kastgard/campaign92324.0 %329
rokgard60.2 %49
rokgard/colony381.0 %99
rokgard/chains902.3 %109
vitgard40.1 %39
telgard40.1 %39
total3,83913381

Every language has 3,839 of 3,839 texts. The number is not comparable with 3,727 from the analysis: keys are being added (3,790 after S1, 3,806 after S2). Kastgard has 1,997 keys, 52 %, the core 44.3 % instead of 52.7 %. The goal of the analysis, 906 keys of the core (24.3 %), has not been reached yet: step M8b (splitting the mixed files of the platform) is not finished, and 84 edges still lead from the core to Kastgard.

Two keys that get saved

With the old code a mission with a traitor and a scenario with betrayal were played up to round 5 and saved; across the whole repository exactly two catalogue keys were found, events.betray_notice and mission.traitor.events.text. Both have an alias in the table RENAMED in js/i18n/i18n.js: t(key) looks under the new name when the old one fails. The table is not made from the whole map, because that would be code for every page for the sake of two keys; the guard G10 checks that the old key is no longer a key, that the new one is, and that the map has that line.

Alphabetical, always: a rule with a guard and a test

After S2 came a reminder about the files: keys are scattered and must always be alphabetical (DESIGN §114). It was not by chance: the tree from S2 sorted the groups by first occurrence. Now the names of each group are in alphabetical order at every level in all 81 files. The order does not depend on the machine or on the language (compareNames in tools/i18n-format.js):

RuleExample
letters by code, case is ignoredliveMusic before livePicture
a run of digits is a number2 before 10, rank.2 before rank.10
a name that begins another comes firstlive before liveMusic
- before digits, digits before _ and lettersA, a-b, a1, a_b, b
the whole key by names from the roota, a.b, a.c, a-b.c

No locale setting: a test refuses localeCompare and Intl in the source of the function. The text and the group stand in one line, and the comment // ---- name ---- goes with the group in front of which it stands.

Where the rule lives

It is a rule with three layers, not an agreement:

  1. The writer. Nobody writes the order by hand: a new key is written anywhere into its group, and node tools/i18n.js --fragments --fix rewrites every file that is not as the writer writes it.
  2. Guard G9 (node tools/i18n.js --fragments --check). In a copy of the tree in the working folder two lines in js/realms/rokgard/i18n/sk.js were swapped, and the guard printed: *G9 1 file(s) of rokgard do not have the names of a group in alphabetical order (…/sk.js); the first: …/sk.js:18 in rokgard, restart_what_chains stands after restart_what_colony: run node tools/i18n.js --fragments --fix*. On the original tree it reports "3839 keys in 9 packages … everything is fine".
  3. Tests. tests/tools/i18n-format.test.js has the test "the real catalogues: each of the 81 files …": for each file it demands an empty list of disorder, the order of keys equal to Format.sortKeys, and the order of Object.keys after running the file equal to the order of the file. The test "the order of the names (DESIGN §114)" checks the full ordering on 160 names (25,600 pairs and 6,000 triples according to §114.1). tests/tools/i18n-fragments.test.js has the test "G9, the order" with mutations: swapped keys, a group in the wrong place, 10 before 2, a comment torn from its group. Both files were run separately on 1 November 2026: 11 of 11 and 16 of 16 passed.

The order was needed only by the listings (--export, the gender check, the overview for translators). The overview had the group "Settings" limited to the first 22 of 36 labels, which after alphabetizing would leave out size, sound and speed; the limit is now 40. The rule applies to files in the list i18nNested, today all nine; a flat file, which the tools read for changes in progress, keeps the order of its lines, but no catalogue is flat.

Why: a new realm and the latches

The decision of 31 October: new realms Vitgard and Telgard will be added gradually and may come into being in parallel (DESIGN §104). The skeleton of each is 3 code files, 9 text files and 4 keys (name, coin, genre and card text). A new game adds its own folder with layers, texts and a mirror of tests. Three independent latches guard it:

LatchWhat it holdsState on 1 November 2026
keys (G1, G5, G7)a file writes only keys its package may read; a key begins with the path of the package; the number of core keys that name the package may only fall36 keys, the table allows 36 (i18nRatchet)
edges of the codetools/packages.js --check: the number of edges per file that break the direction may only shrink; seven of the nine packages are clean, there any new violation fails94 edges in 21 files out of 1,186

Edges changed like this: 120 in 22 files at the move of Kastgard (31 October, A move that must change nothing), 107 at S2, 105 after H5b and 94 after H6, when the tabs of statistics moved from the core to the package of Kastgard (profileview.js 11 → 0). Keys: i18nRatchet was 22 after S1, 41 after S2 (a wider definition: the words kastgard, stacks, campaign were added) and 36 after H6. Of the 94 edges js/ui/app.js alone has 39; from the core 58 lead to Stacks, 24 to Campaign, 2 to Kastgard, 2 to Colony and one each to Rokgard, Lines, Vitgard and Telgard, plus 4 edges from Stacks to Campaign.

What a new realm still changes in the core

The truth is less comfortable than the slogan "no change in the core". A new realm brings its files and texts into its folder, but the registration stays in shared places. In js/core/modetable.js Vitgard and Telgard each have a line (REALMS, lines 45 and 46), and the document calls it a bridge to step M9. The table of registration points in DESIGN §104.5 has 20 lines and 13 of them are marked "shared" (index.html, sw.js, tools/compat.html, the table of packages, js/ui/app.js, style.css, …). The table is from 31 October and has not been recounted. Texts are in a better state, but not entirely: the keys of a game lie in its folder, but what the core must show (the tile, the description in the history) stays as keys of the core, and a new game adds them by step S4 (DESIGN §98.3); the guard only counts them.

Campaign has 923 keys (95 KB raw, 25 KB after gzip in English). They would be saved only in a build without the campaign, but such a build does not exist yet: 34 edges lead from the packages that are not optional into the campaign (packages.js).

The English page today loads 9 text files, in another language 18 (I18n.packFiles; before S1 one, or two). The built build glues them into one file per language, so the built page loads two as before (DESIGN §98.1, §112.5).

What is done, what remains, and what could not be verified

ItemState
texts in the packages, keys with a path (S1, S2)done, 31 October 2026
tree and alphabetical order, guard G9 and testsdone
alias for saved keys (RENAMED, G10)done, 2 keys
S4: 36 keys of the core about the packages as data of the manifestsonly proposed (DESIGN §112.11)
a clean core (M8b), a table of realms outside the core (M9)no, 94 edges
build without the campaignno such build
removing 451 comments of batchesnot done, waiting for an instruction

Among the findings about the documents: docs/I18N.md at the end writes about "22 keys that name the game", while the table says 36. Two tests in tests/tools/i18n-fragments.test.js still have "21 keys of core" and "27 files of Rokgard and 27 of Kastgard" in their names. The heading of DESIGN §112 "every other key" should not mean "every second key" but all the other keys: the path of a package carries all 3,839 (the roots: core 1,700, kastgard 1,997, rokgard 134, vitgard 4, telgard 4).

Sources and notes

  • Brief and analysis: docs/I18N-SPLIT.md, docs/ROADMAP.md ch. 29.
  • Steps and numbers: docs/DESIGN.md §98, §102, §104 and §112 to §115.
  • Measurements of 1 November 2026 (game 0.81.2): node tools/i18n.js --check (3,839 of 3,839), node tools/i18n.js --fragments --check, node tools/packages.js --check (1,186 edges, 94 break), node --test over the format tests.
  • Quotations are from the documents of the game in English, with the date.

What could not be verified: the evidence from DESIGN (the same fingerprint of all nine languages, 36 and 68 screens in four languages, data from the old code, the complete test suites) was not run again while writing; it was read, only the light checks above were run. The offline mode with the service worker sw.js was not tested. The loading time with nine files instead of one was not measured on a network; the prototype from the analysis gave 24–202 ms against 66–104 ms in a hidden panel, which the document itself calls noise. It was not measured whether the alphabet and the trees save time for the authors and translators; DESIGN states it as a reason, not as a result.