跳转到内容
Hagicode Docs
網誌

Steamworks 多語言元數據管理：從手動維護到結構化工作流

编辑此页
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 多語言元數據管理：從手動維護到結構化工作流

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 平台開發應用，並且需要維護多語言內容，希望這套方案能給你帶來一些啟發。多語言內容管理不一定是一件痛苦的事情，有了合適的工具和流程，它可以變得相對輕鬆。或者說，至少不那麼讓人絕望了…

參考資料

如果本文對你有幫助：

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 安装 查看版本与定价