Ir al contenido
Hagicode Docs
Blog

Gestión de metadatos multilingües de Steamworks: del mantenimiento manual a flujos de trabajo estructurados

Edita esta página
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

Gestión de metadatos multilingües de Steamworks: del mantenimiento manual a flujos de trabajo estructurados

La plataforma Steam requiere que los juegos proporcionen contenido de descripción de la tienda en 10 idiomas. El método tradicional de mantenimiento manual es ineficiente y propenso a errores. Este artículo presenta cómo construir un sistema estructurado de gestión de metadatos multilingües a través de HagiCode, logrando un proceso integrado desde la creación de contenido hasta la exportación y publicación.

Antecedentes

La plataforma Steam requiere que los juegos y aplicaciones proporcionen contenido de descripción de la tienda en varios idiomas, incluyendo campos como about (descripción detallada) y short_description (descripción breve). Para productos orientados a la distribución global, generalmente es necesario admitir contenido localizado en 10 idiomas.

Esto parece una tarea sencilla de gestión de contenido, pero cuando realmente se hace, se descubre que hay más problemas de los imaginados.

Primero, la carga de trabajo de mantenimiento es enorme. 10 idiomas multiplicados por 2 campos equivale a 20 bloques de contenido que deben gestionarse. Editar manualmente cambiando de idioma en el backend del sitio web de Steamworks no es eficiente. Cada actualización de contenido requiere repetir este proceso, basta decirlo.

En segundo lugar, el contenido disperso es difícil de gestionar. El contenido multilingüe generalmente se dispersa en diferentes herramientas y documentos, careciendo de un formato de almacenamiento local unificado. El control de versiones se vuelve difícil y la colaboración del equipo es propensa a errores. Después de todo, las cosas dispersas son como recuerdos esparcidos, es difícil encontrarlos.

Además, la gestión del contenido de DLC y la aplicación principal está fragmentada. Si tu juego tiene varios DLC, cada DLC necesita mantener contenido multilingüe por separado, y la complejidad de la gestión crece exponencialmente. Es como la vida, las cosas se acumulan más y más, y no se sabe por dónde empezar a ordenar.

Finalmente, el formato de exportación no es intuitivo. El formato JSON requerido por Steamworks no coincide con los hábitos de lectura humanos, y la edición manual es propensa a errores. Después de todo, ¿a quién le gusta leer todo ese JSON denso?

Todos estos problemas los encontramos durante el desarrollo real del proyecto HagiCode. Como herramienta de codificación AI orientada al desarrollo global, necesitamos mantener contenido multilingüe completo para la plataforma Steam. El método de mantenimiento tradicional ya no puede satisfacer las necesidades, y necesitamos urgentemente una solución más eficiente. En realidad, no hay otra manera, solo hacerlo uno mismo.

Sobre HagiCode

La solución compartida en este artículo proviene de nuestra experiencia práctica en el proyecto HagiCode. HagiCode es una herramienta de codificación AI que admite múltiples proveedores de AI y editores de código. Durante el desarrollo, necesitamos mantener contenido de tienda multilingüe para la plataforma Steam, lo que nos impulsó a construir un sistema estructurado de gestión de metadatos.

La solución de gestión de metadatos multilingüe compartida en este artículo es precisamente lo que nosotros en HagiCode encontramos y optimizamos en la práctica. Si crees que esta solución tiene valor, muestra que nuestra capacidad de ingeniería no está nada mal—entonces HagiCode en sí también vale la pena prestarle atención. Después de todo, una herramienta que puede resolver problemas es una buena herramienta, ¿verdad?

Conceptos básicos

Idiomas y campos

La lista de idiomas admitidos por Steamworks es bastante completa, cubriendo los mercados principales:

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

Los más utilizados son en-US (inglés), zh-CN (chino simplificado), zh-Hant (chino tradicional), ja-JP (japonés) y ko-KR (coreano). Después de todo, estos idiomas cubren los mercados principales, primero resuelve estos y los demás no son tan aterradores.

Los campos que deben mantenerse incluyen principalmente dos:

  • about: descripción detallada, admite formato de texto enriquecido
  • short_description: descripción breve, con límite de longitud de 300 caracteres

Concepto de alcance

El contenido de la aplicación de Steam se puede dividir en dos ámbitos:

  • Base App: contenido de la aplicación principal
  • DLC: contenido descargable, cada DLC tiene gestión de contenido independiente

Esta distinción es importante porque los DLC generalmente necesitan descripciones de tienda independientes, y un juego puede tener múltiples DLC que necesitan gestionarse de manera uniforme. Es como la vida, algunas cosas son principales, otras son adicionales, pero todas deben gestionarse bien, de lo contrario se convertirá en un caos.

Diseño del modelo de datos

El sistema define un modelo de datos claro para admitir la gestión de contenido multilingüe:

// 10 códigos de idioma admitidos
const STEAMWORKS_SUPPORTED_LOCALES = [
  'zh-CN', 'zh-Hant', 'en-US', 'ja-JP', 'ko-KR',
  'de-DE', 'fr-FR', 'es-ES', 'pt-BR', 'ru-RU'
];


// Campos admitidos
const STEAMWORKS_SUPPORTED_FIELDS = [
  'about',           // descripción detallada
  'short_description' // descripción breve
];


// Alcance del contenido
type SteamworksScopeKind = 'base' | 'dlc';

Este diseño de modelo tiene varios puntos de consideración, ¿cómo decirlo?, en realidad solo queremos hacer las cosas un poco más simples:

  1. Utilizar el formato estándar de códigos de idioma (como zh-CN en lugar de chinese), después de todo, las cosas estándar siempre son más confiables
  2. Enumerar claramente los tipos de campos para facilitar la expansión futura, ¿quién sabe si se necesitarán más campos en el futuro?
  3. Distinguir tipos de alcance para admitir la gestión unificada de Base App y DLC, siempre es bueno separar las cosas claramente

Estructura de almacenamiento de archivos

El contenido se almacena en .hagiclaw-data/steamworks-metadata/ del directorio del proyecto, adoptando una estructura de directorios jerárquica:

.hagiclaw-data/
└── steamworks-metadata/
    └── default-app/
        ├── workspace.json              # lista de configuración del espacio de trabajo
        ├── base/                       # contenido de la aplicación base
        │   ├── en-US/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   ├── zh-CN/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   └── ...
        └── dlc/                        # contenido DLC
            └── turbo-engine/
                ├── en-US/
                │   ├── about.md
                │   └── short_description.md
                └── ...

Este diseño de estructura tiene varias ventajas, o al menos, es mucho mejor que el método anterior:

  1. Legible para humanos: cada contenido es un archivo Markdown independiente que se puede editar directamente, después de todo, el ojo humano siempre prefiere ver cosas claras
  2. Amigable con el control de versiones: los archivos de texto facilitan el seguimiento del historial de cambios y la comparación de diferencias, de esta manera qué se ha modificado se ve de un vistazo
  3. Alta escalabilidad: agregar nuevos idiomas o nuevos campos solo requiere crear nuevos archivos, como construir bloques, agrega lo que quieras
  4. Estructura clara: la estructura de directorios refleja intuitivamente la organización del contenido, no hará que la gente se sienta confundida

workspace.json almacena la configuración del espacio de trabajo, incluyendo la lista de DLC e información de configuración de idiomas. Después de todo, algunas cosas aún necesitan una lista, con el tiempo, ¿quién recuerda qué puso?

Conversión de Markdown a BBCode

Steam utiliza formato de texto enriquecido BBCode en lugar del Markdown estándar. Esto trae una carga de trabajo adicional para la creación de contenido—escribe BBCode directamente o conviértelo manualmente más tarde.

La solución de HagiCode es: permitir que los desarrolladores creen con el familiar Markdown, y el sistema lo convierte automáticamente a Steam BBCode. Después de todo, las personas siempre están acostumbradas a lo que les es familiar, ¿por qué obligarse a adaptarse a esos extraños corchetes?

Reglas de conversión

// conversión de encabezados
# HagiCode        → [h1]HagiCode[/h1]
## Features        → [h2]Features[/h2]


// estilos de texto
**bold text**     → [b]bold text[/b]
*italic text*     → [i]italic text[/i]
`code`            → [code]code[/code]


// enlaces e imágenes
[text](url)       → [url=url]text[/url]
![alt](src)       → [img src="{STEAM_APP_IMAGE}/extras/..."][/img]


// listas
- item 1
- item 2          → [*]item 1
                   [*]item 2
                   (envuelto en [list])

Envoltura de idioma

Al exportar, el contenido debe envolverse con etiquetas de idioma:

wrapWithSteamLanguage(locale: SteamworksLocaleCode, bbcode: string): string {
  // devuelve formato [lang=english]...[/lang]
}

Los códigos de idioma deben asignarse al formato de Steam:

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

Esta relación de mapeo en realidad no es compleja, solo necesita recordarse. Después de todo, cada plataforma tiene sus propias reglas, solo podemos adaptarnos.

Formato de exportación

El JSON exportado debe cumplir con los requisitos de estructura 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 编码工具..."
    }
  }
}

Los puntos clave en realidad no son muchos, solo necesitas recordar estos requisitos de formato:

  1. itemid corresponde al Steam AppID
  2. Use los códigos de idioma de Steam (como schinese) bajo languages
  3. Las rutas de campo usan el formato app[content][fieldName]
  4. El valor es la cadena BBCode convertida

Estas reglas parecen un poco tediosas, pero una vez que te acostumbres, así es. Después de todo, cada plataforma tiene su propio temperamento, solo podemos adaptarnos.

Diseño del servicio API

El sistema proporciona una API REST completa para admitir el flujo de trabajo de gestión de contenido multilingüe:

Cargar espacio de trabajo

GET /api/steamworks/metadata

Devuelve la configuración del espacio de trabajo y el contenido de todos los idiomas y campos. Después de todo, debe haber un lugar para sacar todo y verlo.

Guardar contenido

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

Al guardar, el sistema escribirá el contenido de Markdown en los archivos .md correspondientes. Así no se perderá, después de todo, la memoria siempre no es confiable.

Renderizar vista previa

POST /api/steamworks/metadata/preview


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

Devuelve el resultado de renderizado de Markdown y el resultado de conversión de BBCode para facilitar la vista previa. La vista previa es como mirarse en el espejo, siempre debes ver cómo te ves antes de salir.

Exportar JSON

POST /api/steamworks/metadata/export


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

Genera JSON en formato Steamworks que se puede importar directamente al backend de Steamworks. Este paso en realidad está empaquetando todo y listo para enviar.

Gestión de DLC

POST /api/steamworks/metadata/dlc    // crear
PUT /api/steamworks/metadata/dlc     // actualizar
DELETE /api/steamworks/metadata/dlc  // eliminar

La gestión de DLC incluye crear, actualizar y eliminar la configuración de metadatos del DLC. Después de todo, el DLC también es contenido y debe gestionarse bien.

Flujo de uso

1. Acceder al panel de metadatos

Abra el panel Steamworks Metadata en el espacio de trabajo de HagicLaw, el sistema cargará la configuración y el contenido del espacio de trabajo actual. Todo el trabajo de preparación está listo, puede comenzar.

2. Seleccionar el alcance de edición

Seleccione Base App o un DLC específico en la navegación izquierda. Cada ámbito gestiona su contenido multilingüe de forma independiente. Es como ordenar una habitación, primero clasifica las cosas y luego las recoge una por una.

3. Edición de matriz multilingüe

Expanda los idiomas que necesita editar y edite directamente el contenido de Markdown de about y short_description. El sistema admite:

  • Vista previa de renderizado de Markdown en tiempo real
  • Vista previa de conversión de Steam BBCode
  • Recuento de caracteres y verificación de longitud

Estas funciones de vista previa son bastante útiles, al menos pueden saber cómo se ve lo que escribes. Después de todo, nadie quiere escribir un montón de cosas y finalmente descubrir que el formato está todo mal.

4. Guardar contenido

Haga clic en el botón guardar, el contenido se escribirá automáticamente en los archivos .md correspondientes. Los archivos se incluirán en el control de versiones Git para facilitar el seguimiento de cambios. La acción de guardar es como escribir recuerdos, con el tiempo no se olvidarán.

5. Verificación y verificación

El sistema verificará automáticamente:

  • Si los campos requeridos están completos
  • Si short_description excede los 300 caracteres
  • Si la sintaxis de Markdown es correcta

Estas verificaciones pueden evitar algunos errores básicos, después de todo, las personas siempre cometen errores, es bueno tener una máquina ayudando a vigilar.

6. Exportar JSON

Seleccione el ámbito para exportar (Base App o DLC específico), el sistema genera Steamworks JSON que contiene todos los idiomas. Copie el JSON y péguelo en el backend de Steamworks para completar la importación. Este paso se completa, todo el proceso también termina. Todo está listo, solo espera la publicación.

Consideraciones

Mapeo de códigos de idioma

El en-US en el sistema corresponde a english de Steam, zh-CN corresponde a schinese. Esta relación de mapeo se procesa automáticamente al exportar, pero debe prestar atención al editar JSON manualmente. Después de todo, algunas cosas pueden hacerlas las máquinas, pero otras aún deben recordarse.

Limitaciones de BBCode

Steam solo admite un subconjunto de BBCode, y el Markdown complejo puede no convertirse perfectamente. Se recomienda verificar el resultado de la conversión en la vista previa. La vista previa es como mirarse en el espejo, siempre debes ver cómo te ves antes de salir.

Rutas de imagen

Las imágenes se convertirán al formato de marcador de posición [img src="{STEAM_APP_IMAGE}/extras/..."]. Las imágenes reales deben cargarse por separado en el backend de Steam. Las imágenes a veces son más persuasivas que el texto, pero cargarlas es un poco más problemático.

Validación de campos

short_description tiene un límite de longitud estricto de 300 caracteres, el sistema verificará antes de exportar, pero se recomienda prestar atención para controlar la longitud durante la edición. Después de todo, escribir demasiadas palabras no sirve, la plataforma solo ve las primeras 300, así que solo se puede simplificar.

Control de versiones

Todos los archivos Markdown pueden incluirse en el control de versiones Git para facilitar el seguimiento del historial de cambios y la edición colaborativa. Se recomienda confirmar los cambios regularmente. El control de versiones es como una máquina del tiempo, puede llevarte de vuelta a un momento en el pasado para ver qué escribiste en ese momento.

Gestión de DLC

El itemId del DLC debe corresponder al DLC AppID del backend de Steamworks. Al crear un DLC, asegúrese de que el ID sea preciso. Las cosas de ID, una vez que están mal, son difíciles de cambiar, así que es mejor tener cuidado.

Resumen

El desafío central de la gestión de metadatos multilingües de Steamworks es cómo mantener de manera eficiente grandes cantidades de contenido multilingüe. A través de un modelo de datos estructurado, almacenamiento de archivos amigable para humanos y un proceso automatizado de conversión y exportación, podemos transformar este tedioso proceso en un flujo de trabajo de creación de contenido gestionable.

Esta solución se ha demostrado efectiva en la práctica del proyecto HagiCode. Nosotros pasamos de un estado de mantenimiento manual y propenso a errores a un flujo de trabajo estructurado, verificable y colaborativo. Esto no solo mejora la eficiencia, sino que también reduce errores humanos. Después de todo, cuando las herramientas están bien hechas, las cosas se vuelven simples.

Si está desarrollando aplicaciones para la plataforma Steam y necesita mantener contenido multilingüe, espero que esta solución pueda darle algunas ideas. La gestión de contenido multilingüe no tiene por qué ser algo doloroso, con las herramientas y procesos adecuados, puede volverse relativamente fácil. O al menos, no tan desesperante…

Referencias

Si este artículo te ayuda:

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