DEV Community

Hagicode
Hagicode

Posted on • Originally published at docs.hagicode.com

Steamworks Multilingual Metadata Management: From Manual Maintenance to Structured Workflow

#steamworks #bbcode

Steamworks Multilingual Metadata Management: From Manual Maintenance to Structured Workflow

The Steam platform requires games to provide store descriptions in 28 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 release.

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, localization content in 28 languages is typically required.

This sounds like a simple content management task, but when you actually start working on it, you discover there are more problems than you imagined.

First, the maintenance workload is enormous. 28 languages multiplied by 2 fields equals 56 content blocks that need to be managed. Manually switching languages for editing in the Steamworks website backend is indeed inefficient. Every content update requires repeating this process—it's painful to even talk about it.

Second, scattered content is difficult to manage. Multilingual content is typically 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—when you want to find them, you can't.

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

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

These were all problems we encountered 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 could no longer meet our needs, and we urgently needed a more efficient solution. Actually, there's no other way—we had to build it ourselves.

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 drove us to build a structured metadata management system.

The multilingual metadata management solution shared in this article is exactly what we actually refined through trial and optimization 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 supports a fairly complete list of languages, covering major markets:

en-US, fr-FR, it-IT, de-DE, es-ES,
bg-BG, cs-CZ, da-DK, nl-NL, fi-FI,
el-GR, hu-HU, id-ID, ja-JP, ko-KR,
nb-NO, pl-PL, pt-BR, pt-PT, ro-RO,
ru-RU, zh-CN, es-419, sv-SE, th-TH,
zh-TW, tr-TR, uk-UA, vi-VN
Enter fullscreen mode Exit fullscreen mode

The most commonly used are en-US (English), zh-CN (Simplified Chinese), zh-TW (Traditional Chinese), ja-JP (Japanese), and ko-KR (Korean). After all, these languages cover major markets—once you get these done, 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 limit

Scope Concept

Steam app 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 typically 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 properly, or things become a mess.

Data Model Design

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

// 28 supported language codes
const STEAMWORKS_SUPPORTED_LOCALES = [
  'en-US', 'fr-FR', 'it-IT', 'de-DE', 'es-ES',
  'bg-BG', 'cs-CZ', 'da-DK', 'nl-NL', 'fi-FI',
  'el-GR', 'hu-HU', 'id-ID', 'ja-JP', 'ko-KR',
  'nb-NO', 'pl-PL', 'pt-BR', 'pt-PT', 'ro-RO',
  'ru-RU', 'zh-CN', 'es-419', 'sv-SE', 'th-TH',
  'zh-TW', 'tr-TR', 'uk-UA', 'vi-VN'
];

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

// Content scope
type SteamworksScopeKind = 'base' | 'dlc';
Enter fullscreen mode Exit fullscreen mode

There are a few considerations in this model design—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 extension—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
                └── ...
Enter fullscreen mode Exit fullscreen mode

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 edited directly—after all, human eyes prefer to see things clearly
  2. Version control friendly: Text files make it easy to track change history and compare differences—so what was changed is clear at a glance
  3. Strong extensibility: Adding new languages or fields only requires creating new files—like building blocks, add whatever you want
  4. Clear structure: The directory structure intuitively reflects how content is organized—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 in familiar Markdown, and the system automatically converts it to Steam BBCode. After all, people are always accustomed to what they're familiar with—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])
Enter fullscreen mode Exit fullscreen mode

Language Wrapping

When exporting, content needs to be wrapped with language tags:

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

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

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

This mapping relationship isn't actually that complicated, 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 meet Steamworks' structure 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 编码工具..."
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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 seem 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
Enter fullscreen mode Exit fullscreen mode

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

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": "简短文本..."
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

When saving, the system writes Markdown content to 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这是关于..."
}
Enter fullscreen mode Exit fullscreen mode

Returns Markdown rendering result and BBCode conversion result for easy previewing. Preview is like looking in a mirror—you should at least see what you look like before going out.

Export JSON 

POST /api/steamworks/metadata/export

{
  "scopeId": "base-app",
  "scopeKind": "base"
}
Enter fullscreen mode Exit fullscreen mode

Generates Steamworks-format JSON that can be directly imported into the Steamworks backend. This step is essentially packaging everything up, ready for shipping.

DLC Management 

POST /api/steamworks/metadata/dlc    // Create
PUT /api/steamworks/metadata/dlc     // Update
DELETE /api/steamworks/metadata/dlc  // Delete
Enter fullscreen mode Exit fullscreen mode

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

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. Like organizing a room—first categorize things, then clean them up one by one.

3. Multilingual Matrix Editing

Expand the languages you need 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 is automatically written to corresponding .md files. Files are included in Git version control for easy change tracking. Saving is like writing down memories—they won't be forgotten even after a long time.

5. Validation Checks

The system automatically checks:

  • 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, 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

The system's en-US 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—check what you look like before going out.

Image Paths

Images are 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 troublesome to upload.

Field Validation

short_description has a strict 300-character limit. The system validates 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 be concise.

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

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 manual, 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 well-made, things become simple.

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

References

If this article helped you:

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Top comments (0)