Aller au contenu
Hagicode Docs
Blog

Gestion des métadonnées multilingues Steamworks : de la maintenance manuelle au flux de travail structuré

Modifier cette page
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

Gestion des métadonnées multilingues Steamworks : de la maintenance manuelle au flux de travail structuré

La plateforme Steam exige que les jeux fournissent du contenu de description de magasin dans 10 langues, et la méthode traditionnelle de maintenance manuelle est inefficace et sujette aux erreurs. Cet article présente comment construire un système structuré de gestion des métadonnées multilingues via HagiCode, réalisant un processus intégré de la création de contenu à l’exportation et la publication.

Contexte

La plateforme Steam exige que les jeux et applications fournissent du contenu de description de magasin multilingue, y compris des champs comme about (description détaillée) et short_description (description courte). Pour les produits destinés à une distribution mondiale, il est généralement nécessaire de prendre en charge le contenu localisé dans 10 langues.

Cela ressemble à un travail simple de gestion de contenu, mais en pratique, on découvre qu’il y a plus de problèmes que prévu.

Premièrement, la charge de maintenance est énorme. 10 langues multipliées par 2 champs équivalent à 20 blocs de contenu à gérer. Modifier manuellement en changeant de langue dans le backend du site Steamworks n’est pas très efficace. Chaque mise à jour de contenu nécessite de répéter ce processus, c’est une corvée qu’on ne souhaite plus revivre.

Deuxièmement, le contenu dispersé est difficile à gérer. Le contenu multilingue est généralement dispersé dans différents outils et documents, sans format de stockage local unifié. Le contrôle de version devient difficile, et la collaboration d’équipe est sujette aux erreurs. Après tout, les choses dispersées sont comme des souvenirs éparpillés, impossibles à retrouver.

Ensuite, la gestion du contenu DLC est séparée de celle de l’application principale. Si votre jeu possède plusieurs DLC, chaque DLC doit maintenir son propre contenu multilingue, et la complexité de gestion croît de manière exponentielle. C’est comme la vie, les choses s’accumulent, et on ne sait pas par où commencer.

Enfin, le format d’exportation n’est pas intuitif. Le format JSON requis par Steamworks ne correspond pas aux habitudes de lecture humaines, et l’édition manuelle est sujette aux erreurs. Après tout, qui a envie de regarder tout ce JSON dense ?

Nous avons rencontré tous ces problèmes lors du développement réel du projet HagiCode. En tant qu’outil de codage IA destiné au développement mondial, nous devions maintenir un contenu multilingue complet pour la plateforme Steam. Les méthodes de maintenance traditionnelles ne pouvaient plus répondre à nos besoins, nous avions besoin urgent d’une solution plus efficace. En fait, il n’y avait pas d’autre choix, il fallait le faire nous-mêmes.

À propos de HagiCode

La solution présentée dans cet article provient de notre expérience pratique dans le projet HagiCode. HagiCode est un outil de codage IA qui prend en charge plusieurs fournisseurs IA et éditeurs de code. Au cours du développement, nous devions maintenir du contenu de magasin multilingue pour la plateforme Steam, ce qui nous a incités à construire un système structuré de gestion des métadonnées.

La solution de gestion des métadonnées multilingues présentée dans cet article est précisément ce que nous avons expérimenté et optimisé dans le développement de HagiCode. Si vous trouvez cette solution précieuse, cela montre que nos capacités d’ingénierie sont plutôt bonnes — alors HagiCode lui-même mérite une attention. Après tout, un outil qui résout des problèmes est un bon outil, n’est-ce pas ?

Concepts fondamentaux

Langues et champs

La liste des langues prises en charge par Steamworks est assez complète, couvrant les principaux marchés :

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

Les plus courantes sont en-US (anglais), zh-CN (chinois simplifié), zh-Hant (chinois traditionnel), ja-JP (japonais) et ko-KR (coréen). Après tout, ces langues couvrent les principaux marchés, une fois celles-ci maîtrisées, les autres semblent moins effrayantes.

Les champs à maintenir comprennent principalement deux éléments :

  • about : description détaillée, prenant en charge le format de texte enrichi
  • short_description : description courte, avec une limite de 300 caractères

Concept de portée

Le contenu de l’application Steam peut être divisé en deux portées :

  • Base App : contenu de l’application principale
  • DLC : contenu téléchargeable, chaque DLC a une gestion de contenu indépendante

Cette distinction est importante car les DLC nécessitent généralement des descriptions de magasin indépendantes, et un jeu peut avoir plusieurs DLC qui doivent être gérés de manière unifiée. Comme dans la vie, certaines choses sont principales, d’autres sont additionnelles, mais tout doit être bien géré, sinon cela deviendra un désordre.

Conception du modèle de données

Le système définit un modèle de données clair pour prendre en charge la gestion du contenu multilingue :

// 10 codes de langue pris en charge
const STEAMWORKS_SUPPORTED_LOCALES = [
  'zh-CN', 'zh-Hant', 'en-US', 'ja-JP', 'ko-KR',
  'de-DE', 'fr-FR', 'es-ES', 'pt-BR', 'ru-RU'
];


// Champs pris en charge
const STEAMWORKS_SUPPORTED_FIELDS = [
  'about',           // description détaillée
  'short_description' // description courte
];


// Portée de contenu
type SteamworksScopeKind = 'base' | 'dlc';

Ce modèle de modèle a plusieurs points de considération, disons simplement que nous voulions rendre les choses un peu plus simples :

  1. Utiliser le format standard de codes de langue (comme zh-CN au lieu de chinese), après tout les choses standard sont toujours plus fiables
  2. Lister explicitement les types de champs pour faciliter les extensions futures, qui sait si nous aurons besoin de plus de champs à l’avenir
  3. Distinguer les types de portée pour prendre en charge la gestion unifiée des applications de base et des DLC, séparer les choses est toujours bon

Structure de stockage des fichiers

Le contenu est stocké dans .hagiclaw-data/steamworks-metadata/ du répertoire du projet, utilisant une structure de répertoires hiérarchique :

.hagiclaw-data/
└── steamworks-metadata/
    └── default-app/
        ├── workspace.json              # liste de configuration de l'espace de travail
        ├── base/                       # contenu de l'application de base
        │   ├── en-US/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   ├── zh-CN/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   └── ...
        └── dlc/                        # contenu DLC
            └── turbo-engine/
                ├── en-US/
                │   ├── about.md
                │   └── short_description.md
                └── ...

Cette conception de structure a plusieurs avantages, ou du moins, c’est mieux que la méthode précédente :

  1. Lisible par l’homme : chaque contenu est un fichier Markdown indépendant qui peut être édité directement, après tout l’œil humain préfère toujours voir les choses clairement
  2. Convivial pour le contrôle de version : les fichiers texte facilitent le suivi de l’historique des modifications et la comparaison des différences, ainsi ce qui a été modifié est clair à première vue
  3. Fortement extensible : ajouter de nouvelles langues ou de nouveaux champs ne nécessite que de créer de nouveaux fichiers, comme des briques à assembler, on ajoute ce qu’on veut
  4. Structure claire : la structure des répertoires reflète intuitivement l’organisation du contenu, ne donnant pas l’impression de chaos

workspace.json stocke la configuration de l’espace de travail, contenant la liste des DLC et les informations de configuration linguistique. Après tout, certaines choses doivent avoir une liste, sinon avec le temps, qui se souvient de ce qu’on a placé.

Conversion Markdown vers BBCode

Steam utilise le format de texte enrichi BBCode au lieu du Markdown standard. Cela apporte une charge de travail supplémentaire à la création de contenu — soit écrire directement en BBCode, soit convertir manuellement plus tard.

La solution de HagiCode est : laisser les développeurs créer avec le Markdown familier, le système convertit automatiquement en Steam BBCode. Après tout, les humains sont toujours habitués aux choses familières, pourquoi forcer à s’adapter à ces accolades bizarres ?

Règles de conversion

// Conversion des titres
# HagiCode        → [h1]HagiCode[/h1]
## Features        → [h2]Features[/h2]


// Styles de texte
**bold text**     → [b]bold text[/b]
*italic text*     → [i]italic text[/i]
`code`            → [code]code[/code]


// Liens et images
[text](url)       → [url=url]text[/url]
![alt](src)       → [img src="{STEAM_APP_IMAGE}/extras/..."][/img]


// Listes
- item 1
- item 2          → [*]item 1
                   [*]item 2
                   (enveloppé dans [list])

Habillage de langue

Lors de l’exportation, le contenu doit être enveloppé avec des étiquettes de langue :

wrapWithSteamLanguage(locale: SteamworksLocaleCode, bbcode: string): string {
  // retourne le format [lang=english]...[/lang]
}

Les codes de langue doivent être mappés au format Steam :

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

Cette relation de mappage n’est pas vraiment complexe, il faut juste s’en souvenir. Après tout, chaque plateforme a ses propres règles, nous ne pouvons que nous adapter.

Format d’exportation

Le JSON exporté doit respecter les exigences de structure de 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 编码工具..."
    }
  }
}

Les points clés ne sont pas nombreux, il faut juste se souvenir de ces exigences de format :

  1. itemid correspond au Steam AppID
  2. Sous languages, utilisez les codes de langue Steam (comme schinese)
  3. Les chemins de champs utilisent le format app[content][fieldName]
  4. La valeur est la chaîne BBCode convertie

Ces règles semblent un peu fastidieuses, mais une fois habitué, c’est comme ça. Après tout, chaque plateforme a son propre tempérament, nous ne pouvons que nous adapter.

Conception du service API

Le système fournit une API REST complète pour prendre en charge le flux de travail de gestion du contenu multilingue :

Charger l’espace de travail

GET /api/steamworks/metadata

Retourne la configuration de l’espace de travail et le contenu de toutes les langues et champs. Après tout, il doit y avoir un endroit pour sortir tout voir.

Enregistrer le contenu

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

Lors de l’enregistrement, le système écrira le contenu Markdown dans les fichiers .md correspondants. Ainsi rien ne sera perdu, après tout la mémoire est toujours peu fiable.

Rendu de l’aperçu

POST /api/steamworks/metadata/preview


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

Retourne le résultat de rendu Markdown et le résultat de conversion BBCode pour faciliter l’aperçu. L’aperçu c’est comme se regarder dans le miroir, il faut toujours voir à quoi on ressemble avant de sortir.

Exporter JSON

POST /api/steamworks/metadata/export


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

Génère un JSON conforme au format Steamworks qui peut être importé directement dans le backend Steamworks. Cette étape consiste en fait à tout emballer, prêt à expédier.

Gestion DLC

POST /api/steamworks/metadata/dlc    // créer
PUT /api/steamworks/metadata/dlc     // mettre à jour
DELETE /api/steamworks/metadata/dlc  // supprimer

La gestion DLC comprend la création, la mise à jour et la suppression des configurations de métadonnées DLC. Après tout, le DLC est aussi du contenu, il doit être bien géré.

Flux d’utilisation

1. Accéder au panneau des métadonnées

Ouvrez le panneau Steamworks Metadata dans l’espace de travail HagicLaw, le système chargera la configuration et le contenu de l’espace de travail actuel. Une fois tous les préparatifs terminés, on peut commencer.

2. Choisir la portée d’édition

Dans la navigation de gauche, choisissez Base App ou un DLC spécifique. Chaque portée gère son propre contenu multilingue. Comme ranger une pièce, d’abord trier les choses, puis les ranger une par une.

3. Édition matricielle multilingue

Développez les langues à modifier, éditez directement le contenu Markdown de about et short_description. Le système prend en charge :

  • Aperçu de rendu Markdown en temps réel
  • Aperçu de conversion Steam BBCode
  • Comptage de caractères et vérification de longueur

Ces fonctions d’aperçu sont en fait assez utiles, au moins on sait à quoi ressemble ce qu’on a écrit. Après tout, personne ne veut écrire un tas de choses et découvrir à la fin que le format est tout faux.

4. Enregistrer le contenu

Cliquez sur le bouton d’enregistrement, le contenu sera automatiquement écrit dans les fichiers .md correspondants. Les fichiers seront inclus dans le contrôle de version Git pour faciliter le suivi des modifications. L’action d’enregistrer, comme écrire des souvenirs, ne sera pas oubliée avec le temps.

5. Vérification

Le système vérifiera automatiquement :

  • Les champs obligatoires sont complets
  • short_description ne dépasse pas 300 caractères
  • La syntaxe Markdown est correcte

Ces vérifications peuvent éviter certaines erreurs basiques, après tout les humains font toujours des erreurs, avoir une machine pour surveiller est toujours bon.

6. Exporter JSON

Choisissez la portée à exporter (Base App ou DLC spécifique), le système génère un JSON Steamworks contenant toutes les langues. Copiez le JSON et collez-le dans le backend Steamworks pour terminer l’importation. Une fois cette étape terminée, tout le processus est terminé. Tout est prêt, en attente de publication.

Précautions

Mappage des codes de langue

Le en-US du système correspond à english de Steam, zh-CN correspond à schinese. Cette relation de mappage est traitée automatiquement lors de l’exportation, mais attention lors de l’édition manuelle du JSON. Après tout, certaines choses peuvent être faites par la machine, mais d’autres doivent être mémorisées.

Limitations BBCode

Steam ne prend en charge qu’un sous-ensemble de BBCode, le Markdown complexe peut ne pas être converti parfaitement. Il est recommandé de vérifier le résultat de la conversion dans l’aperçu. L’aperçu c’est comme se regarder dans le miroir, il faut toujours voir à quoi on ressemble avant de sortir.

Chemins d’images

Les images seront converties au format d’espace réservé [img src="{STEAM_APP_IMAGE}/extras/..."]. Les images réelles doivent être téléchargées séparément dans le backend Steam. Les images sont parfois plus convaincantes que le texte, juste le téléchargement est un peu plus ennuyeux.

Validation des champs

short_description a une limite de longueur stricte de 300 caractères, le système vérifiera avant l’exportation, mais il est recommandé de faire attention à contrôler la longueur lors de l’édition. Après tout, écrire trop de caractères ne sert à rien, la plateforme ne regarde que les 300 premiers, alors il faut simplifier.

Contrôle de version

Tous les fichiers Markdown peuvent être inclus dans le contrôle de version Git pour faciliter le suivi de l’historique des modifications et l’édition collaborative. Il est recommandé de soumettre régulièrement les modifications. Le contrôle de version est comme une machine à voyager dans le temps, qui peut vous ramener à un moment passé pour voir ce que vous avez écrit à l’époque.

Gestion DLC

Le itemId du DLC doit correspondre au DLC AppID du backend Steamworks. Lors de la création d’un DLC, assurez-vous que l’ID est exact. Les ID, une fois faux, sont difficiles à modifier, donc mieux vaut faire attention.

Résumé

Le défi central de la gestion des métadonnées multilingues Steamworks réside dans la maintenance efficace de grandes quantités de contenu multilingue. Grâce à un modèle de données structuré, un stockage de fichiers convivial et un processus d’exportation de conversion automatisé, nous pouvons transformer ce processus fastidieux en flux de travail de création de contenu gérable.

Cette solution s’est avérée efficace dans la pratique du projet HagiCode. Nous sommes passés d’un état de maintenance manuelle et sujet aux erreurs à un flux de travail structuré, vérifiable et collaboratif. Cela a non seulement amélioré l’efficacité, mais aussi réduit les erreurs humaines. Après tout, une fois les outils prêts, les choses deviennent simples.

Si vous développez une application pour la plateforme Steam et que vous devez maintenir du contenu multilingue, j’espère que cette solution pourra vous donner des idées. La gestion du contenu multilingue n’est pas nécessairement une chose douloureuse, avec les bons outils et processus, elle peut devenir relativement facile. Ou du moins, moins désespérée…

Références

Si cet article vous aide :

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