Vonng/ddia: The Chinese Translation of Designing Data-Intensive Applications, Built as a Hugo Site

What Vonng/ddia Actually Is, and Who It Is For

This repository is a translation project, not a software library. The README describes it as the Chinese translation of Designing Data-Intensive Applications, with Martin Kleppmann and Chris Riccomini credited as authors of the second edition and Feng Ruohang (Vonng) as translator. The content covers the second edition across fourteen chapters, and the README states that all fourteen chapter translations are online and under continuing revision. A first-edition translation is still served at a separate path on the same site.

The audience is Chinese-reading engineers who want the book's material on replication, partitioning, transactions, consensus, batch processing and stream processing without working through the English original. The README frames it for architects, DBAs, backend engineers and even product managers. That is a broad claim, but the chapter list supports it: the first part is about data models, storage engines and encoding, which is groundwork rather than specialist material.

What makes the repository more than a text dump is that the text is a buildable site. The top-level layout includes hugo.yaml, layouts/, content/, i18n/, data/ and static/, plus a Makefile and a go.mod. So the same repository serves two distinct users: someone who reads the rendered site, and someone who wants to regenerate it, translate a variant, or export an EPUB.

How the Hugo and OINK Pipeline Produces the Book

The site is generated by Hugo, and the theme is pulled in as a Go module rather than vendored. The go.mod file declares the module path github.com/Vonng/ddia, a Go version, and a single indirect requirement on github.com/pgsty/oink at v1.0.0. That is the whole dependency graph. There is no Node toolchain, no npm install step, and no package manager lockfile in the top-level entries.

The Makefile is where the build logic actually lives, and it is worth reading before you run anything. The default target is dev, which aliases to a hugo server invocation with --renderToMemory and -DFE, meaning drafts, future-dated and expired pages are all rendered and nothing is written to public/. Crucially, that target overrides the theme with HUGO_MODULE_REPLACEMENTS pointing at a local checkout at $HOME/pgsty/oink, so development builds read the theme's working state rather than the version go.mod pins. Every other target keeps the pinned module. If you run make dev without a local OINK checkout at that exact path, the replacement has nothing to point at.

The build target is a plain hugo build. The check target is stricter: it runs go mod verify with GOWORK=off, then hugo with --cleanDestinationDir, --printPathWarnings, --printI18nWarnings and --panicOnWarning. That last flag means any warning fails the build, which is a deliberate choice and explains why the repository can claim stable figure numbering and cross-references. A broken i18n key or a dangling figure reference cannot slip through.

The remaining targets handle derived artifacts. translate runs a Python script through uv with a pinned opencc-python-reimplemented version to generate the Traditional Chinese version. figures and figures-check drive bin/figure-layout.py with --write and --check respectively. epub calls bin/epub, and epub-check runs bin/check-epub.py after it. The README also mentions Markdown and llms.txt output alongside the EPUB export.

Building and Serving the Site Locally

The README says to visit the hosted site for reading, or to use Hugo with the OINK 1.0.0 theme to build it yourself. It does not give a step-by-step install section, so the commands below come from the Makefile targets rather than from prose instructions. You need Hugo and Go available, since the theme resolves through the Go module system.

The simplest path is to let Hugo fetch the pinned theme and serve a production-shaped build:

make serve

That target runs hugo serve with --environment production, --minify, --disableFastRender and --disableLiveReload. You should see Hugo report the server address and then a full rebuild, with minified output. Because live reload is disabled, edits to content will not refresh the browser automatically; you re-run or restart the command.

If you are working on the theme or on drafts, the development target is different:

make dev

This expects a local OINK checkout at $HOME/pgsty/oink and renders to memory with drafts, future and expired pages included. Nothing lands in public/. If that directory does not exist, the module replacement points at nothing and the build will not resolve the theme as intended.

Before you trust a build, run the strict check:

make check

This verifies the module graph with GOWORK=off and then builds with warnings promoted to failures. Expect it to be unforgiving: an i18n warning or a path warning stops the run. That strictness is the point, and it is the fastest way to find out whether your Hugo version behaves like the one the repository was built against.

Generating the Traditional Chinese Variant and the EPUB

Two derived outputs are worth calling out because they are the parts of the repository that behave like software rather than like a manuscript.

The Traditional Chinese version is generated, not hand-maintained, at least in part. The Makefile target runs a script through uv with a pinned converter version:

make translate

This executes bin/zh-tw.py under uv with opencc-python-reimplemented==0.1.7. Pinning the converter matters: character conversion rules change between versions, and an unpinned converter would let a routine dependency update silently alter the published text. The README credits the Traditional Chinese version and its conversion script to a contributor, and points readers at content/tw/_index.md.

The EPUB path is a two-stage target. The first stage builds the book, the second validates it:

make epub-check

That runs bin/epub and then bin/check-epub.py. The existence of a separate checking script is the interesting detail. It implies the EPUB is generated output that can regress, and the project treats that as something to test rather than something to eyeball. The README lists EPUB export among the online version's features, alongside stable figure numbering, cross-references, sequential reading and full-book printing.

Figures get the same treatment. The figures target calls bin/figure-layout.py with --write, and figures-check calls the same script with --check. So figure layout is computed by a script and verified in CI-shaped runs rather than adjusted by hand in the Markdown.

Where the Repository Falls Short

The most concrete limitation is stated by the project itself, in its legal notice. The README says the translator worked for study purposes and personal interest, claims no economic benefit, and states that the translation is for study and research reference, must not be publicly distributed or used commercially, and that readers able to read English should buy the official edition. That is not a footnote you can ignore if you were planning to republish the text or bundle it into a product. The repository LICENSE is CC-BY-4.0, and the README separately defers other rights to the original author and publisher. Those two statements sit next to each other, and anyone building on the content has to reconcile them rather than assume the licence settles it.

The second limitation is the toolchain's fragility. The development target hardcodes $HOME/pgsty/oink as the local theme path. The check target promotes every Hugo warning to a panic. The theme is pinned through a Go module, which means the build depends on Go module resolution working, and the Makefile already needs GOWORK=off in two places to keep a local workspace from interfering. This is a site that is pleasant to consume and somewhat particular to rebuild.

Third, the README does not document rollback, versioned releases, or a changelog. There are no retrieved releases. If a translation revision or a theme bump breaks something, the recovery path is git history, and the README does not describe one. There is also no stated minimum Hugo version, only a Go version in go.mod.

Finally, this is the wrong tool for anyone who wants a Python package. The primary language is listed as Python, but the Python here is bin/ scripts plus a uv invocation in the Makefile. There is nothing to pip install.

How It Compares with the English Original and with Forking

The obvious alternative is the English second edition on O'Reilly's platform. The README notes that the English original offers an online preview there, and that a Simplified Chinese translation was already planned for completion in 2018, with a purchase link to a Chinese retailer. The difference in approach is not just language. The official edition is a curated, editorially reviewed product with a commercial distribution channel. This repository is a community translation with a public contributor list, a revision history in git, and a rendered site that updates as corrections land. If you want a stable, citable artifact with an editorial guarantee, the official edition is the one to cite. If you want the Chinese text in a form you can search, cross-reference, print as a whole book, or convert to EPUB, this is the version that gives you that.

The other alternative is forking this repository to produce your own variant. That is explicitly supported in spirit: the build is a Hugo site with content in content/, translations in i18n/, and a theme pulled as a module, so a fork can change the theme or the content without touching the toolchain. The cost is that you inherit the check target's strictness and the local-theme path assumption. A fork that wants a different theme has to either publish it as a Go module or extend the replacement mechanism, and the Makefile shows only the single-module replacement form. The README does not describe a multi-module or multi-theme setup.

Maintenance, Licence and What to Verify First

The repository is not archived, and the last push was on 2026-09-20. That is one day before the date used for this assessment, which is as current as a repository gets. The README's note that the second edition's fourteen chapters are online and under continuing revision is consistent with that recency. There are no retrieved releases, so there is no version number to pin against; the unit of upgrade here is a commit.

Upgrade cost is mostly the theme. Because OINK is required as a Go module at v1.0.0, bumping it means changing go.mod and re-running make check. The check target will tell you quickly whether the new theme version breaks i18n keys or paths, since warnings panic. The other moving part is the opencc converter pinned in the translate target at 0.1.7; changing it can alter generated Traditional Chinese text, so a diff review after make translate is the sensible step.

On licensing, the repository carries CC-BY-4.0, and the README's legal notice adds restrictions on public distribution and commercial use while deferring other rights to the original author and publisher. Those two positions are not obviously identical, and the repository does not resolve the tension. This is not legal advice; if you intend to redistribute the text or the EPUB, the notice in the README is the statement to read, and a lawyer is the person to ask.

The first thing to verify on your own machine is whether make check passes at all, since it is the gate that the project itself uses. The second is whether $HOME/pgsty/oink exists, because make dev depends on it and make serve does not. The third is the Hugo version, which the repository does not state; the pinned Go version in go.mod is 1.27.0, and that tells you about the module toolchain, not about Hugo.

Editorial conclusion

Adopt it if you want to read or rebuild the Chinese DDIA text as a static site, or if you need the EPUB and figure tooling that the Makefile exposes. Do not adopt it expecting a Python library or an API: the Python in this repository is in bin/ scripts such as zh-tw.py and figure-layout.py, not a package you install. Before committing, run make check to see whether Hugo and the pinned OINK module resolve cleanly on your machine, and read the legal notice, which states the translation is for study and not for commercial distribution.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-4.0
3. Project website
4. README
5. Vonng/ddia on GitHub