Steam 平台要求游戏提供 28 种语言的商店介绍内容，传统的手动维护方式效率低下且容易出错。本文介绍如何通过 HagiCode 构建一套结构化的多语言元数据管理系统，实现从内容创作到导出发布的一体化流程。
Steam 平台要求游戏和应用提供多语言的商店介绍内容，包括 about（详细描述）和 short_description（简短描述）等字段。对于面向全球发行的产品，通常需要支持 28 种语言的本地化内容。
这听起来像是一个简单的内容管理工作，只是实际操作起来，才发现问题比想象中多了不少。
首先，维护工作量巨大。28 种语言乘以 2 个字段，等于 56 个内容块需要管理。在 Steamworks 网站后台手动切换语言进行编辑，效率确实不高。每次更新内容都需要重复这个过程，说多了都是泪。
其次，内容分散难于管理。多语言内容通常分散在不同工具和文档中，缺乏统一的本地存储格式。版本控制变得困难，团队协作也容易出错。毕竟，分散的东西就像散落的记忆，想找都找不到。
再者，DLC 内容与主应用内容管理割裂。如果你的游戏有多个 DLC，每个 DLC 都需要单独维护多语言内容，管理的复杂度呈指数级增长。这就像生活一样，事情越积越多，也不知道从何收拾。
最后，导出格式不直观。Steamworks 要求的 JSON 格式与人类阅读习惯不符，手动编辑容易出错。毕竟谁愿意去看那些密密麻麻的 JSON 呢？
这些问题在 HagiCode 项目的实际开发中都被我们遇到了。作为一个面向全球开发的 AI 编码工具，我们需要为 Steam 平台维护完整的多语言内容。传统的维护方式已经无法满足需求，我们迫切需要一套更高效的解决方案。其实也没什么别的办法，只能自己动手了。
本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 编码工具，支持多种 AI 提供商和代码编辑器。在开发过程中，我们需要为 Steam 平台维护多语言商店内容，这促使我们构建了一套结构化的元数据管理系统。
本文分享的多语言元数据管理方案，正是我们在 HagiCode 开发中实际踩坑、实际优化出来的。如果你觉得这套方案有价值，说明我们的工程实力还不错——那么 HagiCode 本身也值得关注一下。毕竟，能解决问题就是好工具，对吧？
Steamworks 支持的语言列表相当完整，涵盖了主要市场：
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
其中最常用的是 en-US（英语）、zh-CN（简体中文）、zh-TW（繁体中文）、ja-JP（日语）和 ko-KR（韩语）。毕竟这些语言覆盖了主要市场，先把这几个搞定了，其他的也就不那么可怕了。
需要维护的字段主要包括两个：
about：详细描述，支持富文本格式short_description：简短描述，有 300 字符长度限制Steam 应用内容可以分为两个作用域：
这种区分很重要，因为 DLC 通常需要独立的商店描述，而且一个游戏可能有多个 DLC，需要统一管理。就像生活一样，有些东西是主要的，有些是附加的，但都得好好管着，不然就会乱成一团。
系统定义了清晰的数据模型来支撑多语言内容管理：
// 支持的 28 种语言代码
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'
];
// 支持的字段
const STEAMWORKS_SUPPORTED_FIELDS = [
'about', // 详细描述
'short_description' // 简短描述
];
// 内容作用域
type SteamworksScopeKind = 'base' | 'dlc';
这个模型设计有几个考虑点，怎么说呢，其实就是想让事情变得更简单一点：
zh-CN 而不是 chinese），毕竟标准的东西总是更可靠内容存储在项目目录的 .hagiclaw-data/steamworks-metadata/ 下，采用层次化的目录结构：
.hagiclaw-data/
└── steamworks-metadata/
└── default-app/
├── workspace.json # 工作区配置清单
├── base/ # 基础应用内容
│ ├── en-US/
│ │ ├── about.md
│ │ └── short_description.md
│ ├── zh-CN/
│ │ ├── about.md
│ │ └── short_description.md
│ └── ...
└── dlc/ # DLC 内容
└── turbo-engine/
├── en-US/
│ ├── about.md
│ └── short_description.md
└── ...
这种结构设计有几个优点，或者说，至少比之前的方式好多了：
workspace.json 存储工作区配置，包含 DLC 列表和语言配置信息。毕竟有些东西还是得有个清单，不然时间久了，谁还记得自己放了什么。
Steam 使用 BBCode 格式的富文本，而不是标准的 Markdown。这给内容创作带来了额外的工作量——要么直接写 BBCode，要么后期手动转换。
HagiCode 的解决方案是：让开发者用熟悉的 Markdown 创作，系统自动转换为 Steam BBCode。毕竟，人总是习惯于自己熟悉的东西，何必强迫自己去适应那些奇怪的花括号呢。
// 标题转换
# HagiCode → [h1]HagiCode[/h1]
## Features → [h2]Features[/h2]
// 文本样式
**bold text** → [b]bold text[/b]
*italic text* → [i]italic text[/i]
`code` → [code]code[/code]
// 链接和图片
[text](url) → [url=url]text[/url]
 → [img src="{STEAM_APP_IMAGE}/extras/..."][/img]
// 列表
- item 1
- item 2 → [*]item 1
[*]item 2
(包裹在 [list] 中)
导出时需要用语言标签包裹内容：
wrapWithSteamLanguage(locale: SteamworksLocaleCode, bbcode: string): string {
// 返回 [lang=english]...[/lang] 格式
}
语言代码需要映射到 Steam 的格式：
en-US → englishzh-CN → schinesezh-TW → tchineseja-JP → japaneseko-KR → korean这个映射关系其实也不复杂，只是需要记住而已。毕竟每个平台都有自己的规矩，我们只能适应了。
导出的 JSON 需要符合 Steamworks 的结构要求：
{
"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 编码工具..."
}
}
}
关键点其实也不多，只是需要记住这些格式要求罢了：
itemid 对应 Steam AppIDlanguages 下使用 Steam 的语言代码（如 schinese）app[content][fieldName] 格式这些规则看起来有点繁琐，不过习惯了也就那样。毕竟每个平台都有自己的脾气，我们只能适应了。
系统提供了完整的 REST API 来支撑多语言内容管理工作流：
GET /api/steamworks/metadata
返回工作区配置、所有语言和字段的内容。毕竟，总得有个地方把东西都拿出来看看。
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": "简短文本..."
}
}
}
保存时系统会将 Markdown 内容写入对应的 .md 文件。这样就不会丢失了，毕竟记忆总是不可靠的。
POST /api/steamworks/metadata/preview
{
"locale": "zh-CN",
"field": "about",
"content": "# HagiCode\n\n这是关于..."
}
返回 Markdown 渲染结果和 BBCode 转换结果，方便预览。预览这个东西就像照镜子，总得看看自己长什么样再出门吧。
POST /api/steamworks/metadata/export
{
"scopeId": "base-app",
"scopeKind": "base"
}
生成符合 Steamworks 格式的 JSON，可直接导入 Steamworks 后台。这一步其实就是把所有东西打包好，准备发货了。
POST /api/steamworks/metadata/dlc // 创建
PUT /api/steamworks/metadata/dlc // 更新
DELETE /api/steamworks/metadata/dlc // 删除
DLC 管理包括创建、更新和删除 DLC 的元数据配置。毕竟 DLC 也是内容，也得好好管着。
在 HagicLaw 工作区中打开 Steamworks Metadata 面板，系统会加载当前工作区的配置和内容。一切准备工作做好了，就可以开始了。
在左侧导航中选择 Base App 或具体的 DLC。每个作用域独立管理其多语言内容。就像整理房间一样，先把东西分类，然后再一个个收拾。
展开需要编辑的语言，直接编辑 about 和 short_description 的 Markdown 内容。系统支持：
这些预览功能其实挺有用的，至少能知道自己写出来的东西长什么样。毕竟谁也不想写了一堆东西，最后发现格式全错了。
点击保存按钮，内容会自动写入对应的 .md 文件。文件会被纳入 Git 版本控制，便于追踪变更。保存这个动作，就像把记忆写下来一样，时间久了也不会忘。
系统会自动检查：
short_description 是否超过 300 字符这些检查能避免一些低级错误，毕竟人总是会犯错的，有机器帮忙看着点总是好的。
选择要导出的作用域（Base App 或特定 DLC），系统生成包含所有语言的 Steamworks JSON。复制 JSON 粘贴到 Steamworks 后台即可完成导入。这一步完成，整个流程也就结束了。一切准备就绪，只等发布了。
系统中的 en-US 对应 Steam 的 english，zh-CN 对应 schinese。这个映射关系在导出时自动处理，但手动编辑 JSON 时需要注意。毕竟有些事情机器能帮你做，但有些还是得自己记着。
Steam 仅支持 BBCode 的子集，复杂的 Markdown 可能无法完美转换。建议在预览中检查转换结果。预览这东西就像照镜子，总得看看自己长什么样再出门吧。
图片会被转换为 [img src="{STEAM_APP_IMAGE}/extras/..."] 占位符格式。实际图片需要单独上传到 Steam 后台。图片这东西，有时候确实比文字更有说服力，只是上传起来稍微麻烦一点。
short_description 有严格的 300 字符长度限制，系统会在导出前验证，但建议在编辑时就注意控制长度。毕竟写太多字也没用，平台只看前 300 个，那就只能精简了。
所有 Markdown 文件都可以纳入 Git 版本控制，便于追踪变更历史和协作编辑。建议定期提交变更。版本控制就像时间机器，能让你回到过去的某个时刻，看看当时写了什么。
DLC 的 itemId 需要与 Steamworks 后台的 DLC AppID 对应。创建 DLC 时要确保 ID 准确。ID 这种东西，一旦错了就很难改，所以还是小心点好。
Steamworks 多语言元数据管理的核心挑战在于如何高效维护大量的多语言内容。通过结构化的数据模型、人性化的文件存储和自动化的转换导出流程，我们可以将这个繁琐的过程转变为可管理的内容创作工作流。
这套方案在 HagiCode 项目的实践中证明是有效的。我们从一个手动维护、容易出错的状态，转变为一个结构化、可验证、可协作的工作流程。这不仅提高了效率，也减少了人为错误。毕竟，工具做好了，事情也就简单了。
如果你正在为 Steam 平台开发应用，并且需要维护多语言内容，希望这套方案能给你带来一些启发。多语言内容管理不一定是一件痛苦的事情，有了合适的工具和流程，它可以变得相对轻松。或者说，至少不那么让人绝望了......
如果本文对你有帮助：
感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。
本内容采用人工智能辅助协作,最终内容由作者审核并确认。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。