Pular para o conteúdo
Hagicode Docs
Blog

Gerenciamento de Metadados Multilíngues do Steamworks: Da Manutenção Manual a Fluxos de Trabalho Estruturados

Editar 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

Gerenciamento de Metadados Multilíngues do Steamworks: Da Manutenção Manual a Fluxos de Trabalho Estruturados

A plataforma Steam requer que jogos forneçam conteúdo da loja em 10 idiomas. O método tradicional de manutenção manual é ineficiente e propenso a erros. Este artigo apresenta como construir um sistema estruturado de gerenciamento de metadados multilíngues através do HagiCode,实现一体化流程从内容创作到导出发布。

Contexto

A plataforma Steam requer que jogos e aplicativos forneçam conteúdo da loja multilíngue, incluindo campos como about (descrição detalhada) e short_description (descrição breve). Para produtos voltados ao mercado global, geralmente é necessário suportar conteúdo localizado em 10 idiomas.

Isso pode parecer uma tarefa simples de gerenciamento de conteúdo, mas na prática, descobrimos que há mais problemas do que imaginávamos.

Primeiro, a carga de trabalho de manutenção é enorme. 10 idiomas multiplicados por 2 campos equivalem a 20 blocos de conteúdo para gerenciar. Alternar manualmente entre idiomas para edição no site do Steamworks é realmente ineficiente. Cada atualização de conteúdo requer repetir esse processo, e é doloroso falar sobre isso.

Em segundo lugar, o conteúdo disperso é difícil de gerenciar. O conteúdo multilíngue geralmente está disperso em diferentes ferramentas e documentos, sem um formato de armazenamento local unificado. O controle de versões torna-se difícil e a colaboração da equipe é propensa a erros. Afinal, coisas dispersas são como memórias espalhadas, impossíveis de encontrar.

Além disso, o gerenciamento de conteúdo de DLCs e do aplicativo principal é fragmentado. Se o seu jogo tem vários DLCs, cada DLC precisa manter conteúdo multilíngue separadamente, e a complexidade do gerenciamento cresce exponencialmente. É como a vida, as coisas se acumulam, e não sabemos por onde começar.

Finalmente, o formato de exportação não é intuitivo. O formato JSON exigido pelo Steamworks não corresponde aos hábitos de leitura humana, e a edição manual é propensa a erros. Afinal, quem quer olhar para aqueles JSONs densos?

Encontramos todos esses problemas durante o desenvolvimento real do projeto HagiCode. Como uma ferramenta de codificação AI voltada para desenvolvedores globais, precisamos manter conteúdo multilíngue completo para a plataforma Steam. O método tradicional de manutenção já não atende às nossas necessidades, e precisamos urgentemente de uma solução mais eficiente. Na verdade, não há outro jeito, só podemos fazer isso nós mesmos.

Sobre o HagiCode

A solução compartilhada neste artigo vem de nossa experiência prática no projeto HagiCode. HagiCode é uma ferramenta de codificação AI que suporta vários provedores de AI e editores de código. Durante o desenvolvimento, precisamos manter conteúdo da loja multilíngue para a plataforma Steam, o que nos levou a construir um sistema estruturado de gerenciamento de metadados.

A solução de gerenciamento de metadados multilíngues compartilhada neste artigo é exatamente o que otimizamos na prática durante o desenvolvimento do HagiCode. Se você acha que esta solução tem valor, significa que nossa capacidade de engenharia não é ruim - então o próprio HagiCode também vale a pena ser notado. Afinal, ferramentas que resolvem problemas são boas ferramentas, certo?

Conceitos Principais

Idiomas e Campos

A lista de idiomas suportados pelo Steamworks é bastante completa, cobrindo os principais mercados:

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

Os mais comuns são en-US (inglês), zh-CN (chinês simplificado), zh-Hant (chinês tradicional), ja-JP (japonês) e ko-KR (coreano). Afinal, esses idiomas cobrem os principais mercados, primeiro resolvemos esses e os outros não são tão assustadores.

Os campos que precisam ser mantidos incluem principalmente dois:

  • about: descrição detalhada, suporta formato rich text
  • short_description: descrição breve, com limite de 300 caracteres

Conceito de Escopo

O conteúdo do aplicativo Steam pode ser dividido em dois escopos:

  • Base App: conteúdo do aplicativo principal
  • DLC: conteúdo para download, cada DLC tem gerenciamento de conteúdo independente

Essa distinção é importante, pois os DLCs geralmente precisam de descrições de loja independentes, e um jogo pode ter vários DLCs que precisam ser gerenciados uniformemente. Como a vida, algumas coisas são principais, outras são adicionais, mas todas precisam ser bem gerenciadas, caso contrário, tudo se torna uma bagunça.

Design do Modelo de Dados

O sistema define um modelo de dados claro para suportar o gerenciamento de conteúdo multilíngue:

// Códigos de 10 idiomas suportados
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 suportados
const STEAMWORKS_SUPPORTED_FIELDS = [
  'about',           // Descrição detalhada
  'short_description' // Descrição breve
];


// Escopo de conteúdo
type SteamworksScopeKind = 'base' | 'dlc';

Este design de modelo tem vários pontos de consideração, como dizer, na verdade, é apenas tornar as coisas um pouco mais simples:

  1. Use formato de código de idioma padrão (como zh-CN em vez de chinese), afinal, coisas padrão são sempre mais confiáveis
  2. Liste explicitamente os tipos de campos para facilitar expansões futuras, quem sabe se precisaremos de mais campos no futuro
  3. Distinga tipos de escopo para suportar gerenciamento unificado de Base App e DLC, sempre é bom separar as coisas claramente

Estrutura de Armazenamento de Arquivos

O conteúdo é armazenado em .hagiclaw-data/steamworks-metadata/ no diretório do projeto, adotando uma estrutura de diretórios hierárquica:

.hagiclaw-data/
└── steamworks-metadata/
    └── default-app/
        ├── workspace.json              # Lista de configuração do workspace
        ├── base/                       # Conteúdo do aplicativo base
        │   ├── en-US/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   ├── zh-CN/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   └── ...
        └── dlc/                        # Conteúdo DLC
            └── turbo-engine/
                ├── en-US/
                │   ├── about.md
                │   └── short_description.md
                └── ...

Este design de estrutura tem várias vantagens, ou pelo menos, é muito melhor do que o método anterior:

  1. Legível por humanos: cada conteúdo é um arquivo Markdown independente que pode ser editado diretamente, afinal, os olhos humanos ainda preferem ver coisas claras
  2. Amigável ao controle de versões: arquivos de texto facilitam o rastreamento do histórico de alterações e comparação de diferenças, para que você possa ver o que foi alterado de um relance
  3. Alta escalabilidade: adicionar novos idiomas ou novos campos requer apenas criar novos arquivos, como construir blocos, adicionar o que quiser
  4. Estrutura clara: a estrutura de diretórios reflete intuitivamente a organização do conteúdo, não deixando as pessoas confusas

O workspace.json armazena a configuração do workspace, incluindo a lista de DLCs e informações de configuração de idioma. Afinal, algumas coisas ainda precisam de uma lista, caso contrário, com o tempo, quem se lembrará do que colocou.

Conversão de Markdown para BBCode

O Steam usa formato rich text BBCode, não o Markdown padrão. Isso traz trabalho extra para criação de conteúdo - ou escreve BBCode diretamente, ou converte manualmente posteriormente.

A solução do HagiCode é: deixar os desenvolvedores criarem em Markdown familiar, e o sistema converte automaticamente para Steam BBCode. Afinal, as pessoas sempre se acostumam com coisas familiares, por que se forçar a adaptar àquelas chaves estranhas?

Regras de Conversão

// Conversão de títulos
# 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]


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


// Listas
- item 1
- item 2          → [*]item 1
                   [*]item 2
                   (envolto em [list])

Embalagem de Idioma

Ao exportar, é necessário envolver o conteúdo com tags de idioma:

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

Os códigos de idioma precisam ser mapeados para o formato do Steam:

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

Este relacionamento de mapeamento na verdade não é complexo, apenas precisa ser lembrado. Afinal, cada plataforma tem suas próprias regras, só podemos nos adaptar.

Formato de Exportação

O JSON exportado precisa atender aos requisitos de estrutura do 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 编码工具..."
    }
  }
}

Os pontos principais na verdade não são muitos, apenas precisam lembrar esses requisitos de formato:

  1. itemid corresponde ao Steam AppID
  2. Use o código de idioma do Steam em languages (como schinese)
  3. O caminho do campo usa o formato app[content][fieldName]
  4. O valor é a string BBCode convertida

Essas regras parecem um pouco tediosas, mas depois de se acostumar, é assim mesmo. Afinal, cada plataforma tem seu próprio temperamento, só podemos nos adaptar.

Design do Serviço API

O sistema fornece uma API REST completa para suportar o fluxo de trabalho de gerenciamento de conteúdo multilíngue:

Carregar Workspace

GET /api/steamworks/metadata

Retorna a configuração do workspace e o conteúdo de todos os idiomas e campos. Afinal, precisa haver um lugar para tirar tudo e dar uma olhada.

Salvar Conteúdo

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

Ao salvar, o sistema grava o conteúdo Markdown nos arquivos .md correspondentes. Dessa forma, nada será perdido, afinal, a memória é sempre não confiável.

Renderizar Visualização

POST /api/steamworks/metadata/preview


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

Retorna o resultado da renderização Markdown e o resultado da conversão BBCode para facilitar a visualização. Visualizar é como olhar no espelho, sempre precisa ver como você parece antes de sair.

Exportar JSON

POST /api/steamworks/metadata/export


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

Gera JSON no formato Steamworks que pode ser importado diretamente para o painel do Steamworks. Este passo é na verdade empacotar tudo e preparar para envio.

Gerenciamento de DLC

POST /api/steamworks/metadata/dlc    // Criar
PUT /api/steamworks/metadata/dlc     // Atualizar
DELETE /api/steamworks/metadata/dlc  // Excluir

O gerenciamento de DLC inclui criar, atualizar e excluir configurações de metadados de DLC. Afinal, DLC também é conteúdo e precisa ser bem gerenciado.

Fluxo de Uso

1. Acessar o Painel de Metadados

Abra o painel Steamworks Metadata no workspace HagicLaw, e o sistema carregará a configuração e o conteúdo do workspace atual. Toda a preparação está pronta, então pode começar.

2. Selecionar o Escopo de Edição

Selecione Base App ou um DLC específico na navegação à esquerda. Cada escopo gerencia seu conteúdo multilíngue independentemente. Como arrumar o quarto, primeiro classifique as coisas e depois arrume uma por uma.

3. Edição de Matriz Multilíngue

Expanda os idiomas que precisam ser editados e edite diretamente o conteúdo Markdown de about e short_description. O sistema suporta:

  • Visualização de renderização Markdown em tempo real
  • Visualização de conversão Steam BBCode
  • Contagem de caracteres e verificação de comprimento

Essas funções de visualização são realmente úteis, pelo menos você pode saber como o conteúdo que escreve parece. Afinal, ninguém quer escrever um monte de coisas e descobrir que o formato está tudo errado.

4. Salvar Conteúdo

Clique no botão salvar, e o conteúdo será gravado automaticamente nos arquivos .md correspondentes. Os arquivos serão incluídos no controle de versões Git para facilitar o rastreamento de alterações. Salvar é como escrever memórias, que não serão esquecidas com o tempo.

5. Verificação e Validação

O sistema verificará automaticamente:

  • Se os campos obrigatórios estão completos
  • Se short_description excede 300 caracteres
  • Se a sintaxe Markdown está correta

Essas verificações podem evitar alguns erros básicos, afinal, as pessoas sempre cometem erros, é bom ter máquinas ajudando a observar.

6. Exportar JSON

Selecione o escopo para exportar (Base App ou DLC específico), e o sistema gera Steamworks JSON contendo todos os idiomas. Copie o JSON e cole no painel do Steamworks para completar a importação. Este passo completa, todo o fluxo também termina. Tudo pronto, apenas esperando publicação.

Considerações Importantes

Mapeamento de Código de Idioma

O en-US no sistema corresponde a english do Steam, e zh-CN corresponde a schinese. Este relacionamento de mapeamento é processado automaticamente na exportação, mas precisa de atenção ao editar JSON manualmente. Afinal, algumas coisas máquinas podem ajudá-lo, mas algumas ainda precisam ser lembradas por você.

Limitações do BBCode

O Steam suporta apenas um subconjunto de BBCode, e Markdown complexo pode não ser perfeitamente convertido. Recomenda-se verificar o resultado da conversão na visualização. Visualizar é como olhar no espelho, sempre precisa ver como você parece antes de sair.

Caminhos de Imagem

As imagens serão convertidas para o formato de espaço reservado [img src="{STEAM_APP_IMAGE}/extras/..."]. As imagens reais precisam ser carregadas separadamente no painel do Steam. Às vezes, as imagens são mais convincentes do que o texto, apenas o carregamento é um pouco mais problemático.

Validação de Campo

short_description tem um limite estrito de 300 caracteres, o sistema verificará antes da exportação, mas recomenda-se controlar o comprimento durante a edição. Afinal, escrever muitos caracteres é inútil, a plataforma olha apenas os primeiros 300, então só pode ser simplificado.

Controle de Versões

Todos os arquivos Markdown podem ser incluídos no controle de versões Git para facilitar o rastreamento do histórico de alterações e edição colaborativa. Recomenda-se fazer commit das alterações regularmente. Controle de versões é como uma máquina do tempo, permite voltar a um momento no passado e ver o que foi escrito.

Gerenciamento de DLC

O itemId do DLC precisa corresponder ao DLC AppID no painel do Steamworks. Ao criar um DLC, certifique-se de que o ID está preciso. IDs, uma vez errados, são difíceis de corrigir, então é melhor ter cuidado.

Conclusão

O desafio central do gerenciamento de metadados multilíngues do Steamworks é como manter eficientemente grandes quantidades de conteúdo multilíngue. Através de modelo de dados estruturado, armazenamento de arquivo humanizado e processo automatizado de conversão e exportação, podemos transformar este processo tedioso em um fluxo de trabalho gerenciável de criação de conteúdo.

Esta solução provou ser eficaz na prática do projeto HagiCode. Transformamos de um estado de manutenção manual propenso a erros para um fluxo de trabalho estruturado, verificável e colaborativo. Isso não apenas melhorou a eficiência, mas também reduziu erros humanos. Afinal, quando a ferramenta está bem feita, as coisas se tornam simples.

Se você está desenvolvendo aplicativos para a plataforma Steam e precisa manter conteúdo multilíngue, espero que esta solução possa trazer alguma inspiração para você. O gerenciamento de conteúdo multilíngue não precisa necessariamente ser uma coisa dolorosa, com as ferramentas e processos certos, pode se tornar relativamente fácil. Ou pelo menos, não tão desesperador…

Referências

Se este artigo for útil para você:

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