Zum Inhalt springen
Hagicode Docs
Blog

Steamworks mehrsprachige Metadatenverwaltung: Von manueller Wartung zu strukturiertem Workflow

Seite bearbeiten
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 mehrsprachige Metadatenverwaltung: Von manueller Wartung zu strukturiertem Workflow

Die Steam-Plattform verlangt, dass Spiele Store-Beschreibungen in 10 Sprachen bereitstellen. Die traditionelle manuelle Wartung ist ineffizient und fehleranfällig. Dieser Artikel beschreibt, wie man mit HagiCode ein strukturiertes mehrsprachiges Metadatenverwaltungssystem aufbaut, das einen integrierten Workflow von der Inhaltserstellung bis zum Export und Publishing realisiert.

Hintergrund

Die Steam-Plattform verlangt, dass Spiele und Apps mehrsprachige Store-Beschreibungen bereitstellen, einschließlich Felder wie about (detaillierte Beschreibung) und short_description (kurze Beschreibung). Für global veröffentlichte Produkte müssen normalerweise Lokalisierungsinhalte in 10 Sprachen unterstützt werden.

Das klingt nach einer einfachen Content-Management-Aufgabe, aber in der Praxis stellt man fest, dass es mehr Probleme gibt als erwartet.

Erstens ist der Wartungsaufwand enorm. 10 Sprachen mal 2 Felder gleich 20 Content-Blöcke, die verwaltet werden müssen. Manuell zwischen Sprachen im Steamworks-Web-Backend zu wechseln und zu bearbeiten, ist wirklich ineffizient. Jede Inhaltsaktualisierung erfordert eine Wiederholung dieses Prozesses – das ist wirklich frustrierend.

Zweitens sind Inhalte verteilt und schwer zu verwalten. Mehrsprachige Inhalte sind normalerweise über verschiedene Tools und Dokumente verstreut, ohne ein einheitliches lokales Speicherformat. Die Versionskontrolle wird schwierig, und die Teamarbeit führt leicht zu Fehlern. Schließlich sind verstreute Dinge wie verstreute Erinnerungen – man findet einfach nichts.

Drittens ist die Verwaltung von DLC-Inhalten von Hauptanwendungsinhalten getrennt. Wenn Ihr Spiel mehrere DLCs hat, muss jedes DLC separat mehrsprachige Inhalte pflegen, und die Komplexität der Verwaltung wächst exponentiell. Das ist wie im Leben: Die Dinge häufen sich, und man weiß gar nicht, wo man anfangen soll.

Schließlich ist das Exportformat nicht intuitiv. Das von Steamworks erforderliche JSON-Format entspricht nicht den menschlichen Lesegewohnheiten, und das manuelle Bearbeiten ist fehleranfällig. Schließlich will niemand diese dichtgedrängten JSONs ansehen.

Diese Probleme sind wir im HagiCode-Projekt alle begegnet. Als ein auf globale Entwicklung ausgerichtetes AI-Coding-Tool müssen wir vollständige mehrsprachige Inhalte für die Steam-Plattform pflegen. Die traditionelle Wartungsmethode kann den Anforderungen nicht mehr gerecht werden, und wir dringen auf eine effizientere Lösung. Eigentlich gibt es keinen anderen Weg – man muss es selbst machen.

Über HagiCode

Die in diesem Artikel vorgestellte Lösung stammt aus unseren praktischen Erfahrungen im HagiCode-Projekt. HagiCode ist ein AI-Coding-Tool, das mehrere AI-Anbieter und Code-Editoren unterstützt. Bei der Entwicklung müssen wir mehrsprachige Store-Inhalte für die Steam-Plattform pflegen, was uns dazu veranlasst hat, ein strukturiertes Metadatenverwaltungssystem aufzubauen.

Die in diesem Artikel vorgestellte Lösung zur mehrsprachigen Metadatenverwaltung wurde im HagiCode-Development tatsächlich durch Trial-and-Error und Optimierung entwickelt. Wenn Sie diese Lösung wertvoll finden, bedeutet das, dass unsere Engineering-Fähigkeiten ganz gut sind – dann ist HagiCode selbst einen Blick wert. Schließlich ist ein Tool, das Probleme löst, ein gutes Tool, oder?

Kernkonzepte

Sprachen und Felder

Die von Steamworks unterstützte Sprachliste ist ziemlich vollständig und deckt die wichtigsten Märkte ab:

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

Am häufigsten verwendet werden en-US (Englisch), zh-CN (Vereinfachtes Chinesisch), zh-Hant (Traditionelles Chinesisch), ja-JP (Japanisch) und ko-KR (Koreanisch). Schließlich decken diese Sprachen die wichtigsten Märkte ab. Wenn Sie diese erst einmal beherrschen, sind die anderen nicht mehr so schlimm.

Die zu pflegenden Felder umfassen hauptsächlich zwei:

  • about: Detaillierte Beschreibung, unterstützt Rich-Text-Format
  • short_description: Kurze Beschreibung mit 300-Zeichen-Längenbegrenzung

Scope-Konzept

Steam-Anwendungsinhalte können in zwei Scopes unterteilt werden:

  • Base App: Hauptanwendungsinhalte
  • DLC: Downloadbare Inhalte, jedes DLC hat eine eigene Content-Verwaltung

Diese Unterscheidung ist wichtig, da DLCs normalerweise eine eigene Store-Beschreibung benötigen und ein Spiel mehrere DLCs haben kann, die einheitlich verwaltet werden müssen. Wie im Leben sind einige Dinge wichtig, andere sind附加, aber alle müssen gut verwaltet werden, sonst wird alles chaotisch.

Datenmodell-Design

Das System definiert ein klares Datenmodell zur Unterstützung der mehrsprachigen Content-Verwaltung:

// Unterstützte 10 Sprachcodes
const STEAMWORKS_SUPPORTED_LOCALES = [
  'zh-CN', 'zh-Hant', 'en-US', 'ja-JP', 'ko-KR',
  'de-DE', 'fr-FR', 'es-ES', 'pt-BR', 'ru-RU'
];


// Unterstützte Felder
const STEAMWORKS_SUPPORTED_FIELDS = [
  'about',           // Detaillierte Beschreibung
  'short_description' // Kurze Beschreibung
];


// Content-Scope
type SteamworksScopeKind = 'base' | 'dlc';

Dieses Datenmodell-Design hat mehrere Überlegungen, wie soll man sagen, es soll eigentlich die Dinge einfacher machen:

  1. Verwendung von Standard-Sprachcode-Formaten (wie zh-CN statt chinese), schließlich sind Standard-Dinge immer zuverlässiger
  2. Explizite Auflistung der Feldtypen zur einfachen zukünftigen Erweiterung – wer weiß, ob wir später mehr Felder brauchen
  3. Unterscheidung der Scope-Typen zur einheitlichen Verwaltung von Base App und DLC – es ist immer gut, Dinge klar zu trennen

Dateispeicherstruktur

Inhalte werden unter .hagiclaw-data/steamworks-metadata/ im Projektverzeichnis gespeichert, mit einer hierarchischen Verzeichnisstruktur:

.hagiclaw-data/
└── steamworks-metadata/
    └── default-app/
        ├── workspace.json              # Workspace-Konfigurationsliste
        ├── base/                       # Basis-Anwendungsinhalte
        │   ├── en-US/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   ├── zh-CN/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   └── ...
        └── dlc/                        # DLC-Inhalte
            └── turbo-engine/
                ├── en-US/
                │   ├── about.md
                │   └── short_description.md
                └── ...

Diese Struktur hat mehrere Vorteile, oder zumindest ist sie besser als die vorherige Methode:

  1. Menschenlesbar: Jeder Inhalt ist eine unabhängige Markdown-Datei, die direkt bearbeitet werden kann – schließlich bevorzugen menschliche Augen klar erkennbare Dinge
  2. Versionskontroll-freundlich: Textdateien erleichtern die Nachverfolgung von Änderungshistorie und den Vergleich von Unterschieden – so ist auf einen Blick erkennbar, was geändert wurde
  3. Erweiterbar: Hinzufügen neuer Sprachen oder Felder erfordert nur das Erstellen neuer Dateien – wie Bauklötze, fügen Sie einfach hinzu, was Sie wollen
  4. Klare Struktur: Die Verzeichnisstruktur spiegelt intuitiv die Organisationsweise der Inhalte wider und wirkt nicht chaotisch

workspace.json speichert Workspace-Konfigurationen, einschließlich DLC-Liste und Sprachkonfigurationsinformationen. Schließlich brauchen manche Dinge eine Liste – sonst erinnert sich nach langer Zeit niemand mehr daran, was man wo gespeichert hat.

Markdown zu BBCode-Konvertierung

Steam verwendet Rich-Text im BBCode-Format, nicht Standard-Markdown. Dies bringt zusätzliche Arbeit für die Inhaltserstellung mit sich – entweder direkt BBCode schreiben oder später manuell konvertieren.

HagiCodes Lösung ist: Lassen Sie Entwickler mit vertrautem Markdown erstellen, das System konvertiert automatisch zu Steam BBCode. Schließlich gewöhnt man sich immer an das Vertraute – warum sollte man sich zwingen, sich an seltsame geschweifte Klammern anzupassen?

Konvertierungsregeln

// Überschriftenkonvertierung
# HagiCode        → [h1]HagiCode[/h1]
## Features        → [h2]Features[/h2]


// Textstile
**bold text**     → [b]bold text[/b]
*italic text*     → [i]italic text[/i]
`code`            → [code]code[/code]


// Links und Bilder
[text](url)       → [url=url]text[/url]
![alt](src)       → [img src="{STEAM_APP_IMAGE}/extras/..."][/img]


// Listen
- item 1
- item 2          → [*]item 1
                   [*]item 2
                   (eingeschlossen in [list])

Sprachverpackung

Beim Export müssen Inhalte mit Sprachtags verpackt werden:

wrapWithSteamLanguage(locale: SteamworksLocaleCode, bbcode: string): string {
  // Gibt [lang=english]...[/lang]-Format zurück
}

Sprachcodes müssen zu Steams Format gemappt werden:

  • en-US → english
  • zh-CN → schinese
  • zh-Hant → tchinese
  • ja-JP → japanese
  • ko-KR → korean

Diese Mapping-Beziehung ist eigentlich nicht kompliziert, man muss sie sich nur merken. Schließlich hat jede Plattform ihre eigenen Regeln, wir müssen uns anpassen.

Exportformat

Das exportierte JSON muss Steams Strukturanforderungen entsprechen:

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

Die wichtigsten Punkte sind eigentlich nicht viele, man muss sich nur diese Formatanforderungen merken:

  1. itemid entspricht der Steam AppID
  2. Unter languages werden Steams Sprachcodes verwendet (wie schinese)
  3. Feldpfade verwenden das Format app[content][fieldName]
  4. Werte sind konvertierte BBCode-Strings

Diese Regeln sehen etwas mühsam aus, aber man gewöhnt sich daran. Schließlich hat jede Plattform ihr eigenes Temperament, wir müssen uns anpassen.

API-Service-Design

Das System bietet eine vollständige REST API zur Unterstützung des mehrsprachigen Content-Management-Workflows:

Workspace laden

GET /api/steamworks/metadata

Gibt Workspace-Konfiguration und Inhalte aller Sprachen und Felder zurück. Schließlich braucht man irgendwo, um alle Dinge anzusehen.

Inhalte speichern

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": "简短文本..."
    }
  }
}

Beim Speichern schreibt das System Markdown-Inhalte in die entsprechenden .md-Dateien. So geht nichts verloren – schließlich ist das Gedächtnis immer unzuverlässig.

Render-Vorschau

POST /api/steamworks/metadata/preview


{
  "locale": "zh-CN",
  "field": "about",
  "content": "# HagiCode\n\n这是关于..."
}

Gibt Markdown-Render-Ergebnisse und BBCode-Konvertierungsergebnisse zurück, bequem zur Vorschau. Die Vorschau ist wie ein Spiegel – man sollte sehen, wie man aussieht, bevor man ausgeht.

JSON exportieren

POST /api/steamworks/metadata/export


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

Generiert Steamworks-konformes JSON, das direkt in das Steamworks-Backend importiert werden kann. Dieser Schritt packt实际上 alle Dinge zusammen und bereitet sie zum Versenden vor.

DLC-Verwaltung

POST /api/steamworks/metadata/dlc    // Erstellen
PUT /api/steamworks/metadata/dlc     // Aktualisieren
DELETE /api/steamworks/metadata/dlc  // Löschen

Die DLC-Verwaltung umfasst das Erstellen, Aktualisieren und Löschen von DLC-Metadatenkonfigurationen. Schließlich sind DLCs auch Inhalte und müssen gut verwaltet werden.

Verwendungsablauf

1. Metadaten-Panel aufrufen

Öffnen Sie das Steamworks Metadata Panel im HagicLaw Workspace, das System lädt die Konfiguration und Inhalte des aktuellen Workspace. Wenn alle Vorbereitungen getroffen sind, kann es losgehen.

2. Bearbeitungs-Scope auswählen

Wählen Sie im linken Navigationsbereich Base App oder ein spezifisches DLC aus. Jeder Scope verwaltet seine mehrsprachigen Inhalte unabhängig. Wie beim Aufräumen eines Zimmers: Zuerst Dinge sortieren, dann einzeln aufräumen.

3. Mehrsprachige Matrix-Bearbeitung

Erweitern Sie die zu bearbeitenden Sprachen und bearbeiten Sie direkt die Markdown-Inhalte von about und short_description. Das System unterstützt:

  • Echtzeit-Markdown-Render-Vorschau
  • Steam BBCode-Konvertierungsvorschau
  • Zeichenanzahl und Längenprüfung

Diese Vorschaufunktionen sind tatsächlich ziemlich nützlich – zumindest weiß man, wie die geschriebenen Dinge aussehen. Schließlich will niemand einen Haufen Dinge schreiben und am Ende feststellen, dass das Format völlig falsch ist.

4. Inhalte speichern

Klicken Sie auf die Speichern-Schaltfläche, der Inhalt wird automatisch in die entsprechenden .md-Dateien geschrieben. Dateien werden in die Git-Versionskontrolle aufgenommen, was die Nachverfolgung von Änderungen erleichtert. Speichern ist wie das Aufschreiben von Erinnerungen – nach langer Zeit vergisst man nicht.

5. Validierungsprüfung

Das System überprüft automatisch:

  • Ob Pflichtfelder vollständig sind
  • Ob short_description 300 Zeichen überschreitet
  • Ob Markdown-Syntax korrekt ist

Diese Prüfungen vermeiden einige niedere Fehler – schließlich machen Menschen immer Fehler, und es ist gut, wenn Maschinen helfen, aufzupassen.

6. JSON exportieren

Wählen Sie den zu exportierenden Scope (Base App oder spezifisches DLC), das System generiert Steamworks-JSON mit allen Sprachen. Kopieren Sie das JSON und fügen Sie es in das Steamworks-Backend ein, um den Import abzuschließen. Wenn dieser Schritt abgeschlossen ist, ist der gesamte Prozess beendet. Alles ist vorbereitet, nur noch veröffentlicht.

Hinweise

Sprachcode-Mapping

en-US im System entspricht english von Steam, zh-CN entspricht schinese. Diese Mapping-Beziehung wird beim Export automatisch verarbeitet, aber beim manuellen Bearbeiten von JSON ist Vorsicht geboten. Schließlich können Maschinen manche Dinge für Sie tun, aber manches müssen Sie sich selbst merken.

BBCode-Einschränkungen

Steam unterstützt nur eine Untermenge von BBCode, komplexes Markdown kann möglicherweise nicht perfekt konvertiert werden. Es wird empfohlen, das Konvertierungsergebnis in der Vorschau zu überprüfen. Die Vorschau ist wie ein Spiegel – man sollte sehen, wie man aussieht, bevor man ausgeht.

Bildpfade

Bilder werden in das Platzhalterformat [img src="{STEAM_APP_IMAGE}/extras/..."] konvertiert. Tatsächliche Bilder müssen separat in das Steam-Backend hochgeladen werden. Bilder sind manchmal überzeugender als Text, nur ist das Hochladen etwas umständlicher.

Feldvalidierung

short_description hat eine strikte 300-Zeichen-Längenbegrenzung, das System überprüft vor dem Export, aber es wird empfohlen, beim Bearbeiten auf die Längenkontrolle zu achten. Schließlich nützt es nichts, zu viel zu schreiben – die Plattform sieht nur die ersten 300, also muss man gekürzt werden.

Versionskontrolle

Alle Markdown-Dateien können in die Git-Versionskontrolle aufgenommen werden, was die Nachverfolgung von Änderungshistorie und gemeinsames Bearbeiten erleichtert. Es wird empfohlen, Änderungen regelmäßig zu committen. Die Versionskontrolle ist wie eine Zeitmaschine – sie lässt Sie zu einem bestimmten Moment in der Vergangenheit zurückkehren und sehen, was Sie damals geschrieben haben.

DLC-Verwaltung

Die itemId des DLC muss mit der DLC AppID des Steamworks-Backends übereinstimmen. Erstellen Sie DLCs erst, wenn die ID korrekt ist. IDs sind schwer zu korrigieren, wenn sie einmal falsch sind, also Vorsicht walten lassen.

Zusammenfassung

Die Kernherausforderung bei der Steamworks-mehrsprachigen Metadatenverwaltung liegt darin, wie man effizient große Mengen mehrsprachiger Inhalte pflegt. Durch ein strukturiertes Datenmodell, menschenfreundliche Dateispeicherung und automatisierte Konvertierungs- und Exportprozesse können wir diesen mühsamen Prozess in einen handhabbaren Content-Creation-Workflow verwandeln.

Diese Lösung hat sich in der Praxis im HagiCode-Projekt als wirksam erwiesen. Wir haben uns von einem manuellen, fehleranfälligen Zustand zu einem strukturierten, validierbaren, kollaborativen Workflow entwickelt. Dies hat nicht nur die Effizienz verbessert, sondern auch menschliche Fehler reduziert. Schließlich: Wenn das Tool gut ist, werden die Dinge einfach.

Wenn Sie Anwendungen für die Steam-Plattform entwickeln und mehrsprachige Inhalte pflegen müssen, hoffe ich, dass diese Lösung Ihnen einige Inspirationen bieten kann. Die mehrsprachige Content-Verwaltung muss nicht schmerzhaft sein – mit den richtigen Tools und Prozessen kann sie relativ einfach werden. Oder zumindest weniger verzweifelnd…

Referenzen

Wenn dieser Artikel Ihnen hilft:

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