steam-achievement-localizer

name

steam-achievement-localizer

description

Research, translate, and verify Steam UserGameStatsSchema_*.bin achievement names and descriptions through lossless Binary KeyValues parsing, comparison of every language present in the source schema, required online research whenever network tools are available, optional verified references from GaBoron/steam-achievement-translation-library, and organized work/final artifacts compatible with the translation library and installer. Use when preparing, reviewing, applying, or packaging Steam achievement localization for any Steam language.

Steam Achievement Localizer

Translate achievement text without corrupting Steam Binary KeyValues or treating English as the only source of meaning.

Scope

Use scripts/steam_bkv_tool.py for deterministic schema parsing, project preparation, translation application, verification, packaging, and optional local schema discovery. Keep language judgment and source evaluation with the agent.

Do not replace the live Steam file. Produce a verified canonical BIN and ZIP, then direct ordinary installation and restoration work to GaBoron/steam-achievement-translation-installer. Use GaBoron/steam-achievement-translation-library as the shared translation-data source and submission target.

Project Layout

Keep every task inside one project directory:

localization/<app_id>-<target_language>/
|-- input/
|   `-- UserGameStatsSchema_<app_id>.bin
|-- work/
|   |-- manifest.json
|   |-- sources.json
|   |-- translations.csv
|   `-- references/                  # created only when a verified reference exists
`-- final/                           # created only after apply succeeds
    |-- UserGameStatsSchema_<app_id>.bin
    |-- UserGameStatsSchema_<app_id>.zip
    `-- report.json

Keep every task artifact inside this project.

Workflow

1. Establish the schema path and target Steam language. Run find-schema only when the user asks to locate a local schema:

   python <skill>\scripts\steam_bkv_tool.py find-schema --app-id 123456
   

2. Prepare one project. Omit --workspace to use localization/<app_id>-<language>. Use --offline only when network access is genuinely unavailable or the user explicitly forbids it:

   python <skill>\scripts\steam_bkv_tool.py prepare --schema "C:\path\UserGameStatsSchema_123456.bin" --target-language schinese
   

   Preparation proves byte-identical roundtrip in memory, copies the source into input/, exports one editable work/translations.csv, creates the research manifest, and checks the connected translation library. When a matching primary schema exists, it is downloaded with size and SHA-256 verification under work/references/translation-library/ and exposed in library_* CSV columns.

3. Read work/manifest.json and every language column in work/translations.csv. Compare every language present in the source schema, including partial fields. Never translate from English alone when other language fields exist. Treat differences between languages as evidence about terminology, tone, ambiguity, proper nouns, and omitted context; do not mechanically translate any one language.

4. Research external context. When web, browser, connector, or other network access is available, online research is mandatory. Search the game name, achievement IDs, official localization, developer material, Steam pages, trusted wikis, and useful community references in relevant languages. Prefer official or first-party sources, then the connected translation library, then reputable secondary sources. Record every source actually used in work/sources.json with its URL, kind, and a concise note. Set network_access to unavailable only after network tools are unavailable or fail; never use it merely to skip research.

5. Record every source-schema language actually reviewed in consulted_schema_languages. Fill target_name and target_description for every row. Use translation_notes for ambiguity, terminology choices, source conflicts, wordplay, or proper nouns. Preserve placeholders and intentional punctuation. Keep text single-line and free of NUL, tabs, line breaks, and control characters. Correct invalid cells before applying the translation.

6. Apply only after the translation and research files are complete:

   python <skill>\scripts\steam_bkv_tool.py apply --workspace "localization\123456-schinese"
   

   Application refuses missing or extra achievement IDs, incomplete target text, unreviewed schema languages, absent online sources when network access is marked available, changed source hashes, duplicate language nodes, non-target-language modifications, failed roundtrips, or changed achievement counts.

7. Review final/report.json and the canonical outputs. The ZIP must contain exactly one root-level UserGameStatsSchema_<app_id>.bin, matching the translation-library contribution contract. The canonical BIN is suitable for preview or installation through the companion installer.

Binary Safety Rules

• Preserve node order, repeated keys, numeric bytes, tokens, icons, hidden flags, stats, and every non-target language field.
• Match translations by stable achievement API ID, never by row number or English text.
• Add or update only display/name/<target_language> and display/desc/<target_language> string nodes.
• Require byte-identical parse/serialize roundtrips for both source and localized data.
• Never overwrite the original schema or install back into Steam from this skill.

Completion Report

Report the source path and confirm it was not modified; project directory; source and localized SHA-256; roundtrip result; achievement count; source languages reviewed; online sources used or why network was unavailable; translation-library match; target-language coverage; and the three paths under final/.