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

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

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

背景

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

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

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

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

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

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

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

关于 HagiCode

本文分享的方案来自我们在 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 应用内容可以分为两个作用域：

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

这种区分很重要，因为 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';

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

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

参考资料

• Steamworks Documentation - Store Metadata
• Steam BBCode Guide
• HagiCode 项目地址：github.com/HagiCode-or…
• HagiCode 官网：hagicode.com

如果本文对你有帮助：

• 来 GitHub 给个 Star：github.com/HagiCode-or…
• 访问官网了解更多：hagicode.com
• 观看正式版演示视频：www.bilibili.com/video/BV1z4…
• 一键安装体验：docs.hagicode.com/installatio…
• Desktop 桌面端快速安装：hagicode.com/desktop/

原文与版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。 本内容采用人工智能辅助协作,最终内容由作者审核并确认。

• 本文作者: newbe36524
• 原文链接: docs.hagicode.com/go?platform…
• 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!