Управление многоязычными метаданными Steamworks: от ручного обслуживания к структурированному рабочему процессу

9 мая 2026 г.

Управление многоязычными метаданными Steamworks: от ручного обслуживания к структурированному рабочему процессу

Платформа Steam требует от игр предоставлять контент описания магазина на 10 языках. Традиционный метод ручного обслуживания неэффективен и подвержен ошибкам. В этой статье рассказывается, как с помощью HagiCode создать структурированную систему управления многоязычными метаданными, реализуя интегрированный процесс от создания контента до экспорта и публикации.

Предпосылки

Платформа Steam требует от игр и приложений предоставлять многоязычный контент описания магазина, включая такие поля, как about (подробное описание) и short_description (краткое описание). Для продуктов, ориентированных на глобальный выпуск, обычно требуется поддержка локализованного контента на 10 языках.

Это звучит как простая задача управления контентом, но на практике оказывается, что проблем гораздо больше, чем можно было представить.

Во-первых, огромный объем работы по обслуживанию. 10 языков умножить на 2 поля — это 20 контентных блоков, которые нужно управлять. Ручное переключение языков для редактирования на веб-сайте Steamworks действительно неэффективно. Каждое обновление контента требует повторения этого процесса — рассказывать об этом — сплошная боль.

Во-вторых, контент разбросан и его трудно управлять. Многоязычный контент обычно разбросан по разным инструментам и документам, отсутствует унифицированный формат локального хранения. Управление версиями становится затруднительным, а командное сотрудничество часто приводит к ошибкам. Ведь разбросанные вещи подобны рассыпанным воспоминаниям — их невозможно найти.

В-третьих, управление контентом DLC отделено от управления контентом основного приложения. Если в вашей игре несколько DLC, каждому DLC требуется отдельное обслуживание многоязычного контента, а сложность управления растет экспоненциально. Это как в жизни — вещей накапливается всё больше, и непонятно, с чего начать уборку.

Наконец, формат экспорта не интуитивно понятен. Формат JSON, требуемый Steamworks, не соответствует привычкам человеческого чтения, и ручное редактирование подвержено ошибкам. Ведь кому хочется смотреть на эти густонаселенные 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';

В проектировании этой модели есть несколько соображений, как бы это сказать, на самом деле мы просто хотим сделать вещи немного проще:

Использование стандартного формата языковых кодов (например, zh-CN вместо chinese), ведь стандартные вещи всегда более надежны
Явное перечисление типов полей для удобства будущего расширения,谁知道, понадобятся ли в будущем больше полей
Различие типов областей действия для унифицированного управления 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
                └── ...

У этой структуры есть несколько преимуществ, или, по крайней мере, она намного лучше, чем предыдущий способ:

Читаемость для человека: каждый контент — это независимый файл Markdown, который можно редактировать напрямую, ведь человеческий глаз предпочитает видеть четкие вещи
Дружелюбие к управлению версиями: текстовые файлы удобны для отслеживания истории изменений и сравнения различий, так что все изменения видны с первого взгляда
Масштабируемость: добавление новых языков или полей требует только создания новых файлов, как конструктор, что хочешь, то и добавляешь
Четкая структура: структура каталогов наглядно отражает организацию контента, что не вызывает чувства хаоса

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 编码工具..."
    }
  }
}

Ключевые моменты на самом деле не так уж много, просто нужно запомнить эти требования к формату:

itemid соответствует Steam AppID
В languages используется языковой код Steam (например, schinese)
Путь к полю использует формат app[content][fieldName]
Значение — это преобразованная строка 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"
}

Генерирует JSON в формате Steamworks, который можно напрямую импортировать в бэкенд Steamworks. Этот шаг фактически упаковывает всё и готовит к отправке.

Управление DLC

POST /api/steamworks/metadata/dlc    // создание
PUT /api/steamworks/metadata/dlc     // обновление
DELETE /api/steamworks/metadata/dlc  // удаление

Управление DLC включает создание, обновление и удаление конфигурации метаданных DLC. Ведь DLC — это тоже контент, который нужно хорошо управлять.

Рабочий процесс использования

1. Доступ к панели метаданных

Откройте панель Steamworks Metadata в рабочей области HagicLaw, система загрузит конфигурацию и контент текущей рабочей области. Когда вся подготовительная работа завершена, можно начинать.

2. Выбор области редактирования

В левой навигации выберите Base App или конкретный DLC. Каждая область независимо управляет своим многоязычным контентом. Как при уборке комнаты — сначала разделяете вещи, а затем убираете по очереди.

3. Редактирование матрицы многоязычности

Разверните языки, которые нужно отредактировать, и редактируйте контент Markdown для about и short_description напрямую. Система поддерживает:

Предпросмотр рендеринга Markdown в реальном времени
Предпросмотр преобразования Steam BBCode
Подсчет символов и проверку длины

Эти функции предпросмотра на самом деле довольно полезны, по крайней мере можно знать, как выглядит то, что вы написали. Ведь никто не хочет писать кучу вещей, а в конце обнаружить, что формат весь неправильный.

4. Сохранение контента

Нажмите кнопку сохранения, контент автоматически запишется в соответствующие файлы .md. Файлы будут включены в управление версиями Git для удобства отслеживания изменений. Сохранение — это как записывание воспоминаний, со временем не забудете.

5. Проверка и валидация

Система автоматически проверит:

Полноту обязательных полей
Превышает ли short_description 300 символов
Правильность синтаксиса Markdown

Эти проверки могут избежать простых ошибок, ведь люди всегда ошибаются, и полезно, когда машина помогает следить.

6. Экспорт JSON

Выберите область для экспорта (Base App или конкретный DLC), система сгенерирует Steamworks JSON, содержащий все языки. Скопируйте JSON и вставьте в бэкенд Steamworks для завершения импорта. Когда этот шаг завершен, весь процесс заканчивается. Всё готово, только ждет публикации.

Меры предосторожности

Сопоставление языковых кодов

en-US в системе соответствует english в Steam, zh-CN соответствует schinese. Это соотношение автоматически обрабатывается при экспорте, но при ручном редактировании JSON нужно обратить внимание. Ведь некоторые вещи машина может сделать за вас, но некоторые нужно помнить самому.

Ограничения BBCode

Steam поддерживает только подмножество BBCode, сложный Markdown может быть не полностью преобразован. Рекомендуется проверять результат преобразования в предпросмотре. Предпросмотр — это как зеркало, всегда нужно посмотреть, как вы выглядите, прежде чем выходить.

Пути к изображениям

Изображения будут преобразованы в формат заполнителя [img src="{STEAM_APP_IMAGE}/extras/..."]. Фактические изображения нужно отдельно загрузить в бэкенд Steam. Изображения иногда более убедительны, чем текст, только загрузка немного麻烦нее.

Проверка полей

short_description имеет строгое ограничение длины в 300 символов, система проверит перед экспортом, но рекомендуется контролировать длину при редактировании. Ведь писать слишком много символов бесполезно, платформа смотрит только первые 300, поэтому нужно упростить.

Управление версиями

Все файлы Markdown могут быть включены в управление версиями Git для удобства отслеживания истории изменений и совместного редактирования. Рекомендуется регулярно коммитить изменения. Управление версиями — это как машина времени, позволяющая вернуться в определенный момент в прошлом и посмотреть, что было написано тогда.

Управление DLC

itemId DLC должен соответствовать DLC AppID в бэкенде Steamworks. При создании DLC нужно убедиться, что ID точен. ID — это такая вещь, если ошибешься, трудно исправить, поэтому лучше быть осторожным.

Заключение

Основная проблема управления многоязычными метаданными Steamworks заключается в том, как эффективно поддерживать большой объем многоязычного контента. С помощью структурированной модели данных, человекоориентированного файлового хранилища и автоматизированного процесса преобразования и экспорта мы можем превратить этот утомительный процесс в управляемый рабочий процесс создания контента.

Это решение доказало свою эффективность в практике проекта HagiCode. Мы перешли от состояния ручного обслуживания и подверженности ошибкам к структурированному, проверяемому и совместному рабочему процессу. Это не только повысило эффективность, но и уменьшило человеческие ошибки. Ведь когда инструмент сделан хорошо, дела становятся проще.

Если вы разрабатываете приложение для платформы Steam и вам нужно поддерживать многоязычный контент, надеюсь, это решение даст вам некоторые идеи. Управление многоязычным контентом не обязательно должно быть болезненным, с подходящими инструментами и процессами оно может стать относительно простым. Или, по крайней мере, не столь отчаянным…

Справочные материалы

Документация Steamworks - Store Metadata
Руководство по Steam BBCode
Адрес проекта HagiCode: github.com/HagiCode-org/site
Официальный сайт HagiCode: hagicode.com

Если эта статья была вам полезна:

Приходите на GitHub и поставьте звезду: github.com/HagiCode-org/site
Посетите официальный сайт для получения дополнительной информации: hagicode.com
Посмотрите видеодемонстрацию официальной версии: www.bilibili.com/video/BV1z4oWB3EpY/
Установка одним кликом для опыта: docs.hagicode.com/installation/docker-compose
Быстрая установка на рабочем столе Desktop: hagicode.com/desktop/

开始使用 HagiCode

一次安装，几分钟上手

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

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