pgdoc-cn: Building Chinese PostgreSQL Manuals from SGML Sources

What pgdoc-cn Changes About Chinese PostgreSQL Documentation

pgdoc-cn solves a documentation-language problem rather than a database runtime problem. The China PostgreSQL Users Group formed a volunteer translation group in December 2013 to promote PostgreSQL use in China. The repository holds translated SGML files that correspond to PostgreSQL manuals, and the project explains that those files can be compiled into formats such as HTML and PDF. The intended users are Chinese-speaking PostgreSQL administrators, developers, educators, and readers who need the official manual in Chinese. It does not contain a server, client, migration engine, or extension.

The repository selects one concrete patch release for each supported PostgreSQL major version. Based on the README, the maintained documentation directories cover PostgreSQL 15.7, 16.8, 17.5, and 18.3. Older versions from 9.3 through 14 are retained in branches named after their major version, including 9.3.1, 9.4.4, 9.5.3, 9.6.0, 10.1, 11.2, 12.2, 13.1, and 14.1. This version-oriented layout is important because a manual branch is tied to a particular release rather than serving as an unversioned collection of interchangeable files.

The translation process has changed over time. The README says later work uses machine translation and model proofreading, with individual quality problems improved through user feedback. Readers who depend on exact command syntax, option semantics, or security guidance should still inspect the translated passage and report discrepancies. The repository does not describe a separate automated quality gate for every translated paragraph.

Repository Layout and the SGML Build Model

The repository stores translated SGML under `docs`, while the top-level entries include `docbook`, `docs`, and `tools`. The README describes PostgreSQL documentation source files as SGML, encoded in UTF-8 with Unix-style line endings. Those files are designed to be placed into the corresponding `doc/src/sgml` directory of a PostgreSQL source tree. The PostgreSQL source tree then supplies the normal configuration and build process used to generate the manual.

This architecture means pgdoc-cn is a source overlay rather than a complete, independently runnable documentation site. The translated files need a matching PostgreSQL release because the documentation build expects the surrounding source structure, configuration, styles, and associated inputs. The repository's online manual provides a separate reading path, while the offline manuals are linked from GitHub Releases and a Baidu Netdisk location.

The repository supports feedback at two levels. GitHub Issues are accepted for reporting a problem with its chapter and paragraph location, and Pull requests can correct the source. The Gitee mirror is intended to make access easier within China and accepts Issues, but it does not support Pull requests. For contributors, the source file is the place to make a correction. For readers who do not build the manual, the online pages provide “问题报告” and “纠错本页面” links for reporting or editing an issue from the page context.

Cloning pgdoc-cn and Preparing PostgreSQL 10.1

The README gives a build example using PostgreSQL 10.1 and requires Linux or UNIX for PostgreSQL 10 and later. The first command clones the translation repository into a local `pgdoc-cn` directory.

git clone https://github.com/postgres-cn/pgdoc-cn.git

The example then downloads the PostgreSQL 10.1 source archive and extracts it. The README does not provide a version-selection command for the other release directories, so a builder must choose the source archive that matches the branch or `docs` version being used.

wget https://ftp.postgresql.org/pub/source/v10.1/postgresql-10.1.tar.gz
tar xzf postgresql-10.1.tar.gz

The source tree is then combined with the translated SGML files. The README uses `cp -rf` to copy the repository's documentation tree into the PostgreSQL 10.1 source tree, so the expected result is a `postgresql-10.1/doc/src/` directory containing the translated `sgml` tree. Because this is an overlay operation, a local change in the copied documentation can be overwritten if the copy is repeated.

Installing SGML Tools and Producing HTML

The README points to PostgreSQL's documentation toolset guide and gives an RHEL or CentOS example. The repository specifies that `docbook-style-xsl` must be version 1.77.0 or later. The following is the exact package installation example in the README.

yum install docbook-dtds docbook-style-xsl fop libxslt opensp

The packages support the SGML and DocBook processing involved in producing the manual. The README references the PostgreSQL documentation toolset and build guides rather than declaring a single toolchain that is guaranteed to work on every distribution. Package names and availability can therefore depend on the operating system package repository. The documented requirement is especially relevant to `docbook-style-xsl`, whose stated minimum version is 1.77.0.

After installation, the build starts from the PostgreSQL source root. The documented sequence configures the source tree, enters the translated documentation directory, and builds HTML with `make`.

cd postgresql-10.1/
./configure
cd doc/src/sgml
make html

The expected output is an HTML index at `postgresql-10.1/doc/src/sgml/html/index.html`. A successful command sequence is not enough to establish translation quality. The generated pages still need a reviewer to check version-specific terminology, code samples, table content, and links. The README gives no separate HTML validation command, test suite, or output comparison for this repository.

PDF and Other Offline Documentation

HTML is only one of the documented outputs. The README says PDF and other offline formats can be produced through the PostgreSQL offline manual release procedure, linking to a repository wiki page. It does not reproduce the full PDF recipe in the main README, so a builder should follow that linked procedure rather than assume that `make html` also produces a checked PDF.

Offline versions are made available through GitHub Releases and a Baidu Netdisk directory. The repository lists release entries for PostgreSQL 15.7, and for PostgreSQL 18.3, 17.5, and 16.8 together in the `v18.3v1.0` release note. The README does not state that every release contains identical file types, nor does it promise a release for each historical branch. Release contents and naming should therefore be checked before automation depends on them.

This split between source builds and release downloads gives users two different paths. Someone who needs to inspect the exact translation sources can clone and compile the repository. Someone who only needs a prepared offline manual can inspect the release links instead. The first path has a toolchain dependency; the second path depends on the repository's published artifacts and their availability.

Version Mismatches and Translation Quality as Failure Modes

The most direct failure mode is using translation files from one PostgreSQL release with a source tree from another. The repository explicitly organizes documentation by concrete release versions, and its build procedure copies files into a matching source tree. The README does not provide a compatibility matrix or an automatic check that rejects a mismatch. A version mismatch can leave the build with missing files, stale text, or documentation structure that does not correspond to the selected PostgreSQL source.

A second limitation is translation accuracy. The README states that later versions use large-model translation and large-model proofreading, while some quality problems are addressed through user feedback. It does not claim that every release has been independently verified by PostgreSQL documentation maintainers. That distinction matters for operational instructions, SQL syntax, security settings, and administrative procedures, where a translated sentence can change the meaning even if the manual renders successfully.

pgdoc-cn is also the wrong tool for someone seeking a live database service or a Chinese-language interface to PostgreSQL. It stores documentation, not server binaries, and its build commands compile documentation after the PostgreSQL source has been obtained. The repository is useful when the requirement is readable Chinese reference material, not when the requirement is localized database software.

Maintenance Signals, Licence, and Contribution Boundaries

The repository is not archived, and its last push was on 2026-04-26. The recorded release history includes `v15.7v1.0` on 2025-03-01 and `v18.3v1.0` on 2026-04-12. These facts show recent repository activity and specific translation releases, but they do not establish that every supported PostgreSQL version receives simultaneous updates. The README's version list should be checked for the precise release being documented.

The repository states that use of the translated documentation follows the PostgreSQL licence and links to PostgreSQL's licence page. GitHub metadata reports no recognised licence (NOASSERTION). Anyone distributing or incorporating the manual should inspect the repository's `COPYRIGHT` file and the linked PostgreSQL licence terms for the applicable notices and conditions.

Contribution cost is higher for PDF or custom output because the builder must prepare a compatible PostgreSQL source tree and SGML toolchain. Changes to translation text can be narrower: the README asks contributors to identify the issue and chapter or paragraph location, then submit a Pull request. That low-friction correction path is useful for documentation fixes, but it does not remove the need to select the correct release branch and rebuild the affected output.

Editorial conclusion

pgdoc-cn fits developers who need a Chinese PostgreSQL manual, can match the translation to the appropriate PostgreSQL source tree, and accept responsibility for the DocBook build environment. It is a poor fit for users who want an application-level database client, automated database operations, or documentation with no build dependency. Before adoption, check the branch or `docs` directory against the exact PostgreSQL release, review the README's licence statement, the `COPYRIGHT` file and its PostgreSQL licence link, and confirm that the required SGML tools are available on the target system.

Frequently asked questions

Official sources

1. Issues
2. postgres-cn/pgdoc-cn on GitHub
3. Project website
4. README
5. Releases