Skip to content
Hagicode Docs
Blog

Steamworks Multilingual Metadata Management: From Manual Maintenance to Structured Workflows

Edit page
HagiCode for Windows Microsoft Store artwork
HagiCode for Windows is now on Microsoft Store
HagiCode for Windows is officially live on Microsoft Store. Windows users can install it directly from the storefront and stay on the store-managed update path. Open the listing and take a look.
Open Microsoft Store

Steamworks Multilingual Metadata Management: From Manual Maintenance to Structured Workflows

The Steam platform requires games to provide store descriptions in 10 languages. Traditional manual maintenance is inefficient and error-prone. This article introduces how to build a structured multilingual metadata management system through HagiCode, achieving an integrated workflow from content creation to export and publishing.

Background

The Steam platform requires games and applications to provide multilingual store descriptions, including fields like about (detailed description) and short_description (short description). For products released globally, localized content in 10 languages is typically required.

This sounds like a simple content management task, but in practice, you’ll find there are more problems than expected.

First, the maintenance workload is enormous. 10 languages multiplied by 2 fields equals 20 content blocks that need to be managed. Manually switching languages in the Steamworks website backend for editing is indeed inefficient. Every content update requires repeating this process—too much to say about it.

Second, content is scattered and difficult to manage. Multilingual content is usually scattered across different tools and documents, lacking a unified local storage format. Version control becomes difficult, and team collaboration is prone to errors. After all, scattered things are like scattered memories—hard to find when you need them.

Furthermore, DLC content and main application content management are fragmented. If your game has multiple DLCs, each DLC needs to maintain multilingual content separately, and management complexity grows exponentially. It’s like life—things keep piling up, and you don’t know where to start cleaning up.

Finally, the export format is not intuitive. The JSON format required by Steamworks doesn’t align with human reading habits, making manual editing error-prone. After all, who wants to look at that dense JSON?

We encountered all these problems during the actual development of the HagiCode project. As an AI coding tool for global development, we need to maintain complete multilingual content for the Steam platform. Traditional maintenance methods can no longer meet our needs, and we urgently need a more efficient solution. Actually, there’s no other way but to do it yourself.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI coding tool that supports multiple AI providers and code editors. During development, we needed to maintain multilingual store content for the Steam platform, which prompted us to build a structured metadata management system.

The multilingual metadata management solution shared in this article is exactly what we actually stumbled upon and optimized during HagiCode development. If you find this solution valuable, it shows our engineering strength is pretty good—so HagiCode itself is worth paying attention to. After all, a tool that can solve problems is a good tool, right?

Core Concepts

Languages and Fields

Steamworks’ supported language list is quite comprehensive, covering major markets:

zh-CN, zh-Hant, en-US, ja-JP, ko-KR,
de-DE, fr-FR, es-ES, pt-BR, ru-RU

The most commonly used are en-US (English), zh-CN (Simplified Chinese), zh-Hant (Traditional Chinese), ja-JP (Japanese), and ko-KR (Korean). After all, these languages cover major markets—once you get these sorted, the others aren’t so scary.

The main fields that need to be maintained include two:

  • about: Detailed description, supports rich text format
  • short_description: Short description, with a 300-character length limit

Scope Concept

Steam application content can be divided into two scopes:

  • Base App: Main application content
  • DLC: Downloadable content, each DLC has independent content management

This distinction is important because DLCs usually need independent store descriptions, and a game may have multiple DLCs that need unified management. It’s like life—some things are primary, some are additional, but they all need to be managed well, or everything becomes a mess.

Data Model Design

The system defines a clear data model to support multilingual content management:

// 10 supported language codes
const STEAMWORKS_SUPPORTED_LOCALES = [
  'zh-CN', 'zh-Hant', 'en-US', 'ja-JP', 'ko-KR',
  'de-DE', 'fr-FR', 'es-ES', 'pt-BR', 'ru-RU'
];


// Supported fields
const STEAMWORKS_SUPPORTED_FIELDS = [
  'about',           // Detailed description
  'short_description' // Short description
];


// Content scope
type SteamworksScopeKind = 'base' | 'dlc';

This model design has several considerations—well, actually, it’s just about making things a bit simpler:

  1. Use standard language code formats (like zh-CN instead of chinese)—after all, standard things are always more reliable
  2. Explicitly list field types for future expansion—who knows if more fields will be needed later
  3. Distinguish scope types to support unified management of Base App and DLC—it’s always good to keep things clear

File Storage Structure

Content is stored in .hagiclaw-data/steamworks-metadata/ in the project directory, using a hierarchical directory structure:

.hagiclaw-data/
└── steamworks-metadata/
    └── default-app/
        ├── workspace.json              # Workspace configuration manifest
        ├── base/                       # Base application content
        │   ├── en-US/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   ├── zh-CN/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   └── ...
        └── dlc/                        # DLC content
            └── turbo-engine/
                ├── en-US/
                │   ├── about.md
                │   └── short_description.md
                └── ...

This structure design has several advantages—or at least, it’s much better than the previous approach:

  1. Human-readable: Each content is an independent Markdown file that can be directly edited—after all, human eyes still prefer to see things clearly
  2. Version control friendly: Text files are easy to track for change history and compare differences—so what was changed is clear at a glance
  3. Strong scalability: Adding new languages or fields only requires creating new files—like building blocks, add whatever you want
  4. Clear structure: Directory structure intuitively reflects the organization of content—won’t make people feel confused

workspace.json stores workspace configuration, including DLC list and language configuration information. After all, some things still need a manifest, otherwise after a while, who remembers what they put where.

Markdown to BBCode Conversion

Steam uses BBCode format for rich text, not standard Markdown. This brings additional workload to content creation—either write BBCode directly or manually convert it later.

HagiCode’s solution is: let developers create content with familiar Markdown, and the system automatically converts it to Steam BBCode. After all, people are always accustomed to familiar things—why force yourself to adapt to those strange curly braces.

Conversion Rules

// Heading conversion
# HagiCode        → [h1]HagiCode[/h1]
## Features        → [h2]Features[/h2]


// Text styles
**bold text**     → [b]bold text[/b]
*italic text*     → [i]italic text[/i]
`code`            → [code]code[/code]


// Links and images
[text](url)       → [url=url]text[/url]
![alt](src)       → [img src="{STEAM_APP_IMAGE}/extras/..."][/img]


// Lists
- item 1
- item 2          → [*]item 1
                   [*]item 2
                   (wrapped in [list])

Language Wrapping

Content needs to be wrapped with language tags when exporting:

wrapWithSteamLanguage(locale: SteamworksLocaleCode, bbcode: string): string {
  // Returns [lang=english]...[/lang] format
}

Language codes need to be mapped to Steam’s format:

  • en-US → english
  • zh-CN → schinese
  • zh-Hant → tchinese
  • ja-JP → japanese
  • ko-KR → korean

This mapping relationship isn’t actually complex, it just needs to be remembered. After all, every platform has its own rules, we can only adapt.

Export Format

The exported JSON needs to comply with Steamworks’ structural requirements:

{
  "itemid": "1158573",
  "languages": {
    "english": {
      "app[content][about]": "[h1]HagiCode[/h1]\n[b]About[/b]...",
      "app[content][short_description]": "AI coding tool..."
    },
    "schinese": {
      "app[content][about]": "[h1]HagiCode[/h1]\n[b]关于[/b]...",
      "app[content][short_description]": "AI 编码工具..."
    }
  }
}

The key points aren’t many, just need to remember these format requirements:

  1. itemid corresponds to Steam AppID
  2. Steam’s language codes (like schinese) are used under languages
  3. Field paths use app[content][fieldName] format
  4. Values are converted BBCode strings

These rules look a bit tedious, but you get used to them. After all, every platform has its own temperament, we can only adapt.

API Service Design

The system provides a complete REST API to support the multilingual content management workflow:

Load Workspace

GET /api/steamworks/metadata

Returns workspace configuration, all languages, and field content. After all, there needs to be a place to pull everything out for review.

Save Content

POST /api/steamworks/metadata


{
  "scopeId": "base-app",
  "scopeKind": "base",
  "values": {
    "en-US": {
      "about": "Markdown content...",
      "short_description": "Short text..."
    },
    "zh-CN": {
      "about": "Markdown 内容...",
      "short_description": "简短文本..."
    }
  }
}

When saving, the system writes Markdown content to the corresponding .md files. This way nothing gets lost—after all, memory is always unreliable.

Render Preview

POST /api/steamworks/metadata/preview


{
  "locale": "zh-CN",
  "field": "about",
  "content": "# HagiCode\n\n这是关于..."
}

Returns Markdown rendering results and BBCode conversion results for easy previewing. Preview is like looking in a mirror—you should always see how you look before going out.

Export JSON

POST /api/steamworks/metadata/export


{
  "scopeId": "base-app",
  "scopeKind": "base"
}

Generates Steamworks-format JSON that can be directly imported into the Steamworks backend. This step is essentially packing everything up and getting ready to ship.

DLC Management

POST /api/steamworks/metadata/dlc    // Create
PUT /api/steamworks/metadata/dlc     // Update
DELETE /api/steamworks/metadata/dlc  // Delete

DLC management includes creating, updating, and deleting DLC metadata configuration. After all, DLC is also content and needs to be managed well.

Usage Workflow

1. Access Metadata Panel

Open the Steamworks Metadata panel in the HagicLaw workspace, and the system will load the current workspace’s configuration and content. Once all preparations are done, you can begin.

2. Select Edit Scope

Select Base App or a specific DLC in the left navigation. Each scope independently manages its multilingual content. It’s like organizing a room—first categorize things, then clean them up one by one.

3. Multilingual Matrix Editing

Expand the languages you want to edit, and directly edit the Markdown content for about and short_description. The system supports:

  • Real-time Markdown rendering preview
  • Steam BBCode conversion preview
  • Character count and length checking

These preview features are actually quite useful—at least you can know what your content looks like. After all, no one wants to write a bunch of stuff only to find the format is completely wrong.

4. Save Content

Click the save button, and content will be automatically written to the corresponding .md files. Files will be included in Git version control for easy change tracking. Saving is like writing down memories—time passes and you won’t forget.

5. Validation Checks

The system will automatically check:

  • Whether required fields are complete
  • Whether short_description exceeds 300 characters
  • Whether Markdown syntax is correct

These checks can avoid some basic errors—after all, humans make mistakes, and it’s always good to have a machine help watch over things.

6. Export JSON

Select the scope to export (Base App or specific DLC), and the system generates Steamworks JSON containing all languages. Copy the JSON and paste it into the Steamworks backend to complete the import. Once this step is done, the entire workflow is complete. Everything is ready, just waiting for release.

Notes

Language Code Mapping

en-US in the system corresponds to Steam’s english, and zh-CN corresponds to schinese. This mapping is handled automatically during export, but needs attention when manually editing JSON. After all, some things machines can help you with, but some you still need to remember yourself.

BBCode Limitations

Steam only supports a subset of BBCode, and complex Markdown may not convert perfectly. It’s recommended to check conversion results in preview. Preview is like looking in a mirror—you should always see how you look before going out.

Image Paths

Images will be converted to [img src="{STEAM_APP_IMAGE}/extras/..."] placeholder format. Actual images need to be uploaded separately to the Steam backend. Images are sometimes more persuasive than text, just a bit more trouble to upload.

Field Validation

short_description has a strict 300-character length limit. The system will validate before export, but it’s recommended to control length during editing. After all, writing too many characters is useless—the platform only looks at the first 300, so you have to simplify.

Version Control

All Markdown files can be included in Git version control for easy change history tracking and collaborative editing. It’s recommended to commit changes regularly. Version control is like a time machine that lets you return to a past moment and see what you wrote then.

DLC Management

A DLC’s itemId needs to correspond to the DLC AppID in the Steamworks backend. When creating a DLC, ensure the ID is accurate. IDs are hard to change once wrong, so it’s better to be careful.

Summary

The core challenge of Steamworks multilingual metadata management lies in how to efficiently maintain large amounts of multilingual content. Through structured data models, human-friendly file storage, and automated conversion export workflows, we can transform this tedious process into a manageable content creation workflow.

This solution has proven effective in the practice of the HagiCode project. We transformed from a manually maintained, error-prone state to a structured, verifiable, collaborative workflow. This not only improved efficiency but also reduced human error. After all, when the tool is good, things become simple.

If you’re developing applications for the Steam platform and need to maintain multilingual content, I hope this solution brings you some inspiration. Multilingual content management doesn’t have to be a painful thing—with the right tools and processes, it can become relatively easy. Or at least, not so hopeless…

References

If this article helps you:

Tags:
相关链接
HagiCode for Windows Microsoft Store artwork
HagiCode for Windows is now on Microsoft Store
HagiCode for Windows is officially live on Microsoft Store. Windows users can install it directly from the storefront and stay on the store-managed update path. Open the listing and take a look.
Open Microsoft Store

开始使用 HagiCode

一次安装，几分钟上手

HagiCode for Windows 在 Microsoft Store 免费提供。打开商店即可安装并保持更新；也可以先对比各版本与定价，再决定从哪个渠道开始。

前往 Microsoft Store 安装 查看版本与定价