跳转到内容
Hagicode Docs
博客

Steamworks 多语言元数据管理：从手动维护到结构化工作流

编辑此页
HagiCode for Windows Microsoft Store artwork
HagiCode for Windows 已上线 Microsoft Store
HagiCode for Windows 现已正式登陆 Microsoft Store，Windows 用户可以直接从商店完成安装并接收渠道更新。现在就打开商店页看看吧。
打开 Microsoft Store

Steamworks 多语言元数据管理：从手动维护到结构化工作流

Steam 平台要求游戏提供 10 种语言的商店介绍内容，传统的手动维护方式效率低下且容易出错。本文介绍如何通过 HagiCode 构建一套结构化的多语言元数据管理系统，实现从内容创作到导出发布的一体化流程。

背景

Steam 平台要求游戏和应用提供多语言的商店介绍内容，包括 about（详细描述）和 short_description（简短描述）等字段。对于面向全球发行的产品，通常需要支持 10 种语言的本地化内容。

这听起来像是一个简单的内容管理工作，只是实际操作起来，才发现问题比想象中多了不少。

首先，维护工作量巨大。10 种语言乘以 2 个字段，等于 20 个内容块需要管理。在 Steamworks 网站后台手动切换语言进行编辑，效率确实不高。每次更新内容都需要重复这个过程，说多了都是泪。

其次，内容分散难于管理。多语言内容通常分散在不同工具和文档中，缺乏统一的本地存储格式。版本控制变得困难，团队协作也容易出错。毕竟，分散的东西就像散落的记忆，想找都找不到。

再者，DLC 内容与主应用内容管理割裂。如果你的游戏有多个 DLC，每个 DLC 都需要单独维护多语言内容，管理的复杂度呈指数级增长。这就像生活一样，事情越积越多，也不知道从何收拾。

最后，导出格式不直观。Steamworks 要求的 JSON 格式与人类阅读习惯不符，手动编辑容易出错。毕竟谁愿意去看那些密密麻麻的 JSON 呢？

这些问题在 HagiCode 项目的实际开发中都被我们遇到了。作为一个面向全球开发的 AI 编码工具，我们需要为 Steam 平台维护完整的多语言内容。传统的维护方式已经无法满足需求，我们迫切需要一套更高效的解决方案。其实也没什么别的办法，只能自己动手了。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 编码工具，支持多种 AI 提供商和代码编辑器。在开发过程中，我们需要为 Steam 平台维护多语言商店内容，这促使我们构建了一套结构化的元数据管理系统。

本文分享的多语言元数据管理方案，正是我们在 HagiCode 开发中实际踩坑、实际优化出来的。如果你觉得这套方案有价值，说明我们的工程实力还不错——那么 HagiCode 本身也值得关注一下。毕竟，能解决问题就是好工具，对吧？

核心概念

语言与字段

Steamworks 支持的语言列表相当完整，涵盖了主要市场：

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

其中最常用的是 en-US（英语）、zh-CN（简体中文）、zh-Hant（繁体中文）、ja-JP（日语）和 ko-KR（韩语）。毕竟这些语言覆盖了主要市场，先把这几个搞定了，其他的也就不那么可怕了。

需要维护的字段主要包括两个：

  • about：详细描述，支持富文本格式
  • short_description：简短描述，有 300 字符长度限制

作用域概念

Steam 应用内容可以分为两个作用域：

  • Base App：主应用内容
  • DLC：下载内容，每个 DLC 有独立的内容管理

这种区分很重要，因为 DLC 通常需要独立的商店描述，而且一个游戏可能有多个 DLC，需要统一管理。就像生活一样，有些东西是主要的，有些是附加的，但都得好好管着，不然就会乱成一团。

数据模型设计

系统定义了清晰的数据模型来支撑多语言内容管理：

// 支持的 10 种语言代码
const STEAMWORKS_SUPPORTED_LOCALES = [
  'zh-CN', 'zh-Hant', 'en-US', 'ja-JP', 'ko-KR',
  'de-DE', 'fr-FR', 'es-ES', 'pt-BR', 'ru-RU'
];


// 支持的字段
const STEAMWORKS_SUPPORTED_FIELDS = [
  'about',           // 详细描述
  'short_description' // 简短描述
];


// 内容作用域
type SteamworksScopeKind = 'base' | 'dlc';

这个模型设计有几个考虑点，怎么说呢，其实就是想让事情变得更简单一点：

  1. 使用标准的语言代码格式（如 zh-CN 而不是 chinese），毕竟标准的东西总是更可靠
  2. 将字段类型明确列出，方便未来扩展，谁知道以后会不会需要更多字段呢
  3. 区分作用域类型，支持 Base App 和 DLC 的统一管理，把事情分清楚总是好的

文件存储结构

内容存储在项目目录的 .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
                └── ...

这种结构设计有几个优点，或者说，至少比之前的方式好多了：

  1. 人类可读：每个内容都是独立的 Markdown 文件，可以直接编辑，毕竟人眼还是更喜欢看清楚的东西
  2. 版本控制友好：文本文件便于追踪变更历史和对比差异，这样改动过什么，一目了然
  3. 扩展性强：添加新语言或新字段只需要创建新文件，就像搭积木一样，想加什么加什么
  4. 结构清晰：目录结构直观反映了内容的组织方式，不会让人觉得混乱

workspace.json 存储工作区配置，包含 DLC 列表和语言配置信息。毕竟有些东西还是得有个清单，不然时间久了，谁还记得自己放了什么。

Markdown 到 BBCode 转换

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]
![alt](src)       → [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 → english
  • zh-CN → schinese
  • zh-Hant → tchinese
  • ja-JP → japanese
  • ko-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 编码工具..."
    }
  }
}

关键点其实也不多，只是需要记住这些格式要求罢了：

  1. itemid 对应 Steam AppID
  2. languages 下使用 Steam 的语言代码（如 schinese）
  3. 字段路径使用 app[content][fieldName] 格式
  4. 值是转换后的 BBCode 字符串

这些规则看起来有点繁琐，不过习惯了也就那样。毕竟每个平台都有自己的脾气，我们只能适应了。

API 服务设计

系统提供了完整的 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 转换结果，方便预览。预览这个东西就像照镜子，总得看看自己长什么样再出门吧。

导出 JSON

POST /api/steamworks/metadata/export


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

生成符合 Steamworks 格式的 JSON，可直接导入 Steamworks 后台。这一步其实就是把所有东西打包好，准备发货了。

DLC 管理

POST /api/steamworks/metadata/dlc    // 创建
PUT /api/steamworks/metadata/dlc     // 更新
DELETE /api/steamworks/metadata/dlc  // 删除

DLC 管理包括创建、更新和删除 DLC 的元数据配置。毕竟 DLC 也是内容，也得好好管着。

使用流程

1. 访问元数据面板

在 HagicLaw 工作区中打开 Steamworks Metadata 面板，系统会加载当前工作区的配置和内容。一切准备工作做好了，就可以开始了。

2. 选择编辑作用域

在左侧导航中选择 Base App 或具体的 DLC。每个作用域独立管理其多语言内容。就像整理房间一样，先把东西分类，然后再一个个收拾。

3. 多语言矩阵编辑

展开需要编辑的语言，直接编辑 about 和 short_description 的 Markdown 内容。系统支持：

  • 实时 Markdown 渲染预览
  • Steam BBCode 转换预览
  • 字符计数和长度检查

这些预览功能其实挺有用的，至少能知道自己写出来的东西长什么样。毕竟谁也不想写了一堆东西，最后发现格式全错了。

4. 保存内容

点击保存按钮，内容会自动写入对应的 .md 文件。文件会被纳入 Git 版本控制，便于追踪变更。保存这个动作，就像把记忆写下来一样，时间久了也不会忘。

5. 验证检查

系统会自动检查：

  • 必填字段是否完整
  • short_description 是否超过 300 字符
  • Markdown 语法是否正确

这些检查能避免一些低级错误，毕竟人总是会犯错的，有机器帮忙看着点总是好的。

6. 导出 JSON

选择要导出的作用域（Base App 或特定 DLC），系统生成包含所有语言的 Steamworks JSON。复制 JSON 粘贴到 Steamworks 后台即可完成导入。这一步完成，整个流程也就结束了。一切准备就绪，只等发布了。

注意事项

语言代码映射

系统中的 en-US 对应 Steam 的 english，zh-CN 对应 schinese。这个映射关系在导出时自动处理，但手动编辑 JSON 时需要注意。毕竟有些事情机器能帮你做，但有些还是得自己记着。

BBCode 限制

Steam 仅支持 BBCode 的子集，复杂的 Markdown 可能无法完美转换。建议在预览中检查转换结果。预览这东西就像照镜子，总得看看自己长什么样再出门吧。

图片路径

图片会被转换为 [img src="{STEAM_APP_IMAGE}/extras/..."] 占位符格式。实际图片需要单独上传到 Steam 后台。图片这东西，有时候确实比文字更有说服力，只是上传起来稍微麻烦一点。

字段验证

short_description 有严格的 300 字符长度限制，系统会在导出前验证，但建议在编辑时就注意控制长度。毕竟写太多字也没用，平台只看前 300 个，那就只能精简了。

版本控制

所有 Markdown 文件都可以纳入 Git 版本控制，便于追踪变更历史和协作编辑。建议定期提交变更。版本控制就像时间机器，能让你回到过去的某个时刻，看看当时写了什么。

DLC 管理

DLC 的 itemId 需要与 Steamworks 后台的 DLC AppID 对应。创建 DLC 时要确保 ID 准确。ID 这种东西，一旦错了就很难改，所以还是小心点好。

总结

Steamworks 多语言元数据管理的核心挑战在于如何高效维护大量的多语言内容。通过结构化的数据模型、人性化的文件存储和自动化的转换导出流程，我们可以将这个繁琐的过程转变为可管理的内容创作工作流。

这套方案在 HagiCode 项目的实践中证明是有效的。我们从一个手动维护、容易出错的状态，转变为一个结构化、可验证、可协作的工作流程。这不仅提高了效率，也减少了人为错误。毕竟，工具做好了，事情也就简单了。

如果你正在为 Steam 平台开发应用，并且需要维护多语言内容，希望这套方案能给你带来一些启发。多语言内容管理不一定是一件痛苦的事情，有了合适的工具和流程，它可以变得相对轻松。或者说，至少不那么让人绝望了…

参考资料

如果本文对你有帮助：

标签:
相关链接
HagiCode for Windows Microsoft Store artwork
HagiCode for Windows 已上线 Microsoft Store
HagiCode for Windows 现已正式登陆 Microsoft Store，Windows 用户可以直接从商店完成安装并接收渠道更新。现在就打开商店页看看吧。
打开 Microsoft Store

开始使用 HagiCode

一次安装，几分钟上手

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

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