콘텐츠로 이동
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. 표준 언어 코드 형식을 사용합니다(예: chinese 대신 zh-CN). 표준은 항상 더 신뢰할 수 있습니다
  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은 표준 Markdown이 아닌 BBCode 형식의 리치 텍스트를 사용합니다. 이것은 콘텐츠 제작에 추가 작업을 가져옵니다. 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 安装 查看版本与定价