Overview
This document proposes an architecture for adding multilingual (i18n) support to the 5e SRD database and API. The goal is to allow community contributors to provide translations of SRD content in additional languages while preserving full backward compatibility with the existing English-only API.
Goals
- Support translated content for any language in the SRD API responses
- Zero breaking changes to existing API consumers (English remains the default)
- Enable community contributions via simple JSON file PRs — no database knowledge required
- Track translation completeness per language and collection
- Remain cache-friendly (Redis)
Non-Goals
- Machine translation or auto-translation tooling
- Translating non-content fields (indexes, API references, numeric values, etc.)
- UI or documentation translation (handled separately in the
docs repo)
Recommended Architecture
Overview
Separate translation JSON source files (one file per language per collection) that are merged at pipeline time into a dedicated {year}-translations MongoDB collection. The base English documents remain unchanged.
This combines two strengths:
- Contributor experience — translations live in flat JSON files, reviewable as git diffs
- API simplicity — translations are resolved at query time by merging a translation document over the base English document, with English as the fallback