logo hsb.horse

Registro de Decisão de Arquitetura

Política de estrutura de implementação de ferramentas

Definir roteamento, limites de feature e propriedade de i18n para adição de ferramentas individuais.

Aceito #tools #architecture #routing #i18n

Traduções

Inglês Japonês

Política de estrutura de implementação de ferramentas

Decisão

  • Usar src/pages/tools/[category]/[tool-slug]/index.astro como estrutura de entrada de página para ferramentas individuais.
  • Seguir a estratégia de URL i18n existente adicionando src/pages/[lang]/tools/[category]/[tool-slug]/index.astro quando rotas localizadas forem necessárias.
  • Manter arquivos de página enxutos e mover a implementação real para src/features/tools/[tool-slug]/.
  • Manter sob a raiz src/features/tools/ apenas preocupações compartilhadas, como carregamento de catálogo, helpers de slug/categoria, UI compartilhada e tipos compartilhados.
  • Armazenar textos específicos de ferramenta em src/features/tools/[tool-slug]/i18n/{lang}.json.
  • Reservar src/i18n apenas para textos compartilhados do site.
  • Promover strings para src/i18n apenas quando o mesmo texto for reutilizado por duas ou mais ferramentas, ou por páginas não relacionadas a ferramentas.
  • Exigir JSON-LD SoftwareApplication em todas as páginas de ferramenta.
  • Exigir breadcrumb visível em todas as páginas de ferramenta e emitir JSON-LD BreadcrumbList correspondente.

Contexto

O catálogo de ferramentas já é gerenciado de forma centralizada, enquanto ferramentas individuais exigem UI e comportamento independentes. Precisávamos de uma estrutura consistente que mantenha cada ferramenta autocontida, evite inflar o i18n global e preserve propriedade compartilhada quando apropriado.

Opções

  • Opção A: colocar todo texto de ferramenta em src/i18n.
  • Opção B: colocar todo texto de ferramenta apenas no diretório de cada ferramenta.
  • Opção C: modelo híbrido (escolhido), no qual texto de ferramenta fica local por padrão e apenas texto realmente compartilhado é centralizado.

Justificativa

  • Manter implementação e texto dentro de cada ferramenta melhora localidade e reduz acoplamento.
  • Manter i18n global focado em textos de site evita crescimento descontrolado e conflitos de merge.
  • A regra híbrida oferece caminho claro para migração de texto compartilhado sem centralização prematura.
  • Arquivos de entrada de página enxutos seguem a separação existente entre página/feature e simplificam manutenção.

Consequências

  • Cada nova ferramenta deve incluir src/features/tools/[tool-slug]/ com implementação e i18n/{lang}.json próprios.
  • Arquivos de rota em src/pages/.../tools/... devem principalmente conectar params a componentes de feature.
  • Metadados de catálogo (title e description para cards de listagem) continuam em docs/tools/*.yaml, conforme definido no ADR existente de catálogo de ferramentas.
  • Times devem seguir a regra de promoção de strings compartilhadas para manter fronteiras claras.
  • Critérios de aceite de páginas de ferramenta passam a incluir tanto dados estruturados SoftwareApplication quanto breadcrumbs visíveis com dados estruturados BreadcrumbList.