Skip to content
ArchmageDocs

L10n Pipeline

Organizing localizable text in game configs usually requires tedious record-keeping — designers or developers must register each translatable string in a dedicated file and assign it a unique key, turning what should be simple edits into a constant chore.

The l10n pipeline removes that burden. Instead of manually creating keys and wiring up references, you write localizable text directly in place. Archmage collects all l10n strings during data export, and emits l10n.json, l10n.yaml, or l10n.csv — ready for translation.

To start using l10n, you first need an l10n.xlsx file to set up the pipeline. The file contains only shared localizable strings to be reused across files. You can generate a starter file using the init subcommand, or craft it manually following the format detailed later in this document. Once ready, pass the file to --l10n during data export.

Terminal window
archmage export -o ./out --l10n configs/l10n.xlsx "configs/*.xlsx"

Pipeline

Section titled “Pipeline”

  1. Parse l10n.xlsx.

  2. Collect all l10n strings from every input.

    Inputs include enum items, l10n.xlsx, and all other files passed to export.

  3. Validate each l10n reference against l10n.xlsx.

    A value using the {{...}} syntax is treated as a reference to a shared l10n string in l10n.xlsx. For example, {{npc1_name}} references the npc1_name entry.

  4. Export each l10n value as a localization key.

    The key replaces the original text in place; the text itself is moved into the aggregate.

  5. Write the aggregate to files.

    Archmage performs a full refresh on each run, overwriting existing files.

The l10n.xlsx

Section titled “The l10n.xlsx”

l10n.xlsx is a special regular table for shared localizable strings.

  • It uses string config IDs, identified by the $% marker in any cell of the first row.
  • It has only one exportable data column, named localizable, of type l10n.
  • If a referenced entry does not exist in l10n.xlsx, Archmage reports an error at export time.
  • Entries in the file can also use {{...}}, but only as redirect hints (no chaining support).
$%
Descriptionlocalizable
Namelocalizable
Typel10n
menu.startPress START to begin
verse1Found a bug, Fixed with shrug. Now it's two - Undo!
ref-example{{menu.start}}

Multiple Worksheets

Section titled “Multiple Worksheets”

If l10n.xlsx contains multiple worksheets, an index table is required to specify which sheets to export. All config IDs across these sheets must remain unique.

**Notes
mainThe main sheet
demo*Matches all demo sheets

Output Formats

Section titled “Output Formats”

--l10n-output-formats selects which file(s) carry the l10n strings.

Value Output File Default
json l10n.json ✓
yaml l10n.yaml
csv l10n.csv

Combine these values with commas to write several at once:

Terminal window
archmage export --l10n l10n.xlsx --l10n-output-formats json,yaml,csv \
  -o ./out "configs/*.xlsx"
{
  "l10n.xlsx[menu.start]": "Press START to begin",
  "l10n.xlsx[verse1]": "Found a bug, Fixed with shrug. Now it's two - Undo!",
  "npc[101].greeting": "Hello, traveler.",
  "mob[702].taunt": "It is a good day to die!",
  "gameSettings.mainMenu.title": "Settings"
}

Translation & Integration

Section titled “Translation & Integration”

Your team can choose one of the generated files — l10n.json, l10n.yaml, or l10n.csv — as the source file for translation. The final localized output must be a JSON file matching the structure of the source file; if your workflow yields other formats, convert them using archmage conv.

At runtime, your game loads the required language files — typically the fallback language and the player’s preferred language — and initializes the global L10n system. Each l10n field then resolves to its localized text by calling an SDK-specific accessor, such as name.Text().