clreq: the W3C requirements set for Chinese text layout

A requirements document with no install step

clreq is not a library, a CLI, or a build plugin. The repository that hosts it is primarily HTML and Markdown, and its default branch is gh-pages, which is where the published pages live. That changes what an evaluation of the project should look like. There is no package to add to package.json and no bundle to ship. What there is, in the words of the project's own description, is a place to explore gaps in support for the Chinese Simplified and Traditional scripts on the Web and in eBooks, and to document requirements.

The audience is therefore narrow and professional: engineers, designers and language specialists who need to know what the correct rendering of Chinese text is, and want an authoritative answer rather than folklore about line breaking and punctuation. The stated motivation is unusually candid. Local users often do not know how to tell the W3C which problems exist for their language on the Web, and the W3C does not know how to reach people who can help when questions come up. The project exists to fix that contact problem as much as the technical one.

A second use is diagnostic. Because the requirements are written down and versioned, a team can point at a specific clause when it disagrees with what a browser does today.

One repository holding three living documents

The repository is not a single document. It publishes three related outputs that share the same source tree and the same review process. The core is Chinese Layout Requirements, tracked in the clreq directory, with a DNOTE at /TR/clreq, an editor's draft hosted at the project homepage, and a link to the latest commits for index.html. Alongside it sit Chinese Script Resources under hani-lreq, which covers the Han ideograph repertoire rather than the Chinese language layout rules, and Chinese Gap Analysis under clreq-gap, which is a separate DNOTE at /TR/clreq-gap.

The top-level layout reflects that split. Directories named src, resources, gap-analysis, homepage, charter, others, tests and zh sit next to index.html, local.css, print.css, a .editorconfig and .gitattributes. The zh directory and the two localized README files, README.zh-Hans.md and README.zh-Hant.md, matter because the audience includes readers who will not work in English.

Two more links round out the picture. Ready-made Counter Styles is offered as a separate W3C note, and a repository file named others/system-font-mappings.md holds recommended system font mappings for generic Chinese font families. The distinction between requirements and supporting advice is drawn inside the repository rather than being blurred.

Gap analysis turns browser bugs into tracked requirements

The mechanism that makes this project more than a prose document is the gap analysis. Topics for discussion are proposed with the gap analysis template hosted by the W3C Internationalization activity site, at w3.org/International/i18n-activity/templates/gap-analysis/gap-analysis_template.html. Reports are then filed as issues against the repository, and the project links filtered issue views directly from its README: one for open questions carrying the question label, one for gap reports, and one for everything that is neither question nor gap.

The work feeds into a language matrix that renders a heat map of language issues on the Web, so a single gap report about, say, punctuation handling in a particular browser ends up visible in a cross-language overview. A third filter points at specification issues raised in the i18n-activity repository under the clreq label, which separates questions about the text of the document from questions about browser behaviour.

The practical consequence for an engineer is that a wrong rendering is not a vague complaint. It becomes a numbered report tied to a template, and eventually either a requirement change or a browser bug.

Editing the multilingual sources comes with its own procedure

Contributing text is not a pull request and merge. The project states plainly that the document is multilingual and that certain steps must be followed when creating or modifying the source text, with the full procedure kept in a file called EDITING.md at the repository root. The README routes both newcomers and seasoned editors to it, alongside W3C guidelines for working with i18n documents on GitHub and separate editorial guidelines for i18n documents. There is also an editorial guideline dedicated to the Hans-Hant glossary, which signals how seriously the simplified versus traditional vocabulary distinction is treated.

Contributors are asked to read and agree with CONTRIBUTING.md before submitting content. The editing model is closer to structured authoring with peer review than to a community codebase, and the existence of .editorconfig, .gitattributes, w3c.json and a .pr-preview.json file in the repository root supports that reading: the tooling handles structure, previews and normalisation, while humans handle wording.

For anyone planning to upstream a change, this is the part to budget time for. The review path is the cost, and it buys consistency across the language versions.

Watching clreq without opening a pull request

Not every user of the project wants to edit it, and the README separates observation from contribution. It explicitly advises against watching the repository and recommends subscribing to the public-i18n-chinese mailing list instead, on the grounds that the list is notified about changes to issues in the repository but also about other W3C Working Group issues relating to the Chinese writing systems. Subscribing means sending a request to the public-i18n-chinese-request address with the subject line subscribe.

A broader option covers Chinese, Japanese and Korean together through the public-i18n-cjk list, requested at public-i18n-cjk-request with the same subject.

Both lists send notification digests, no more than once a day and in digest form, and the README is clear that the public-i18n-chinese archive is used for digests and meeting minutes rather than for technical discussion. Discussion happens in the GitHub issue list.

One practical constraint is spelled out for contributors who prefer Chinese. Issues may be raised in Chinese, but substantive discussions are expected to be summarised in English at some point so that non-Chinese speakers can follow the rationale and contribute comments. That single rule shapes how much of the project any individual can realistically take part in.

Where clreq falls short of what developers usually want

The gap is worth stating plainly. clreq describes what correct behaviour should be; it does not deliver it. Nothing here makes a browser render Chinese text properly, and no font, shaping engine or line breaker ships in the repository. A team with a broken rendering will still finish debugging by itself, and the closest the project comes to a fix is a gap report and, later, a change in a browser or rendering engine elsewhere.

Second, the corpus is uneven. The gap analysis documents exist for Chinese in Simplified and Traditional, but the Chinese layout requirements themselves have to cover two scripts with different historical conventions, and the presence of a dedicated Hans-Hant glossary and a separate Chinese Script Resources document shows that some of the content has to be split out to stay coherent. Readers who only need one variant may spend time navigating structure built for both.

Third, the workflow has a deliberate bottleneck. The requirement that substantive discussion be summarised in English, the template-driven gap reports, and the editor's draft review path all slow down individual contributions in exchange for reach. Teams with a deadline and a single script in production may find that cost disproportionate.

clreq next to hani-lreq and to project-level gap analysis

Two neighbouring paths are easier to confuse with clreq than they should be. The first is hani-lreq, the Chinese Script Resources DNOTE hosted at /TR/hani-lreq, with its own editor's draft under resources. Both live in the same repository and both concern Chinese text, but they answer different questions: clreq concerns layout of Chinese text, while hani-lreq concerns the Han script repertoire and its resources. A team hunting for the correct shape of a specific character set is in the wrong document if it stays in the layout requirements.

The second is the project-level route. Instead of working inside the language-wide task force, the W3C typography community publishes guidance on setting up a gap analysis project of your own, and there is a separate repository for writing i18n tests. That approach analyses one codebase or product against the language requirements and produces findings you own, rather than contributing to a shared task force process.

For most readers the practical contrast is between a shared normative text and a private audit. clreq is the shared text, and the auditable result is the set of numbered gap reports it accumulates.

Licence, releases and who pays for maintenance

The repository carries a licence GitHub cannot classify, listed as Other with a custom licence in LICENCE.md at the repository root, so anyone planning to reuse the text should read that file rather than assume a permissive default. There are no GitHub releases, which means there is no version history to cite in a procurement document and no upgrade step to schedule; the document moves as an editor's draft between dated versions on the W3C site.

On maintenance, the archive flag is off and the last push was on 2026-09-16, so the work is live rather than abandoned. The upgrade cost for a reader is therefore close to zero, because there is nothing to upgrade; the cost falls on anyone trying to change the text, where it is the cost of a reviewed, multilingual editorial process rather than a merge.

Participation itself is structured. The README lists levels of involvement from list subscriber through participant and editor to chair, names the chairs as Yijun CHEN and Eric Q. LIU, and points to W3C staff contacts for requests to join at a higher level. The same section mentions the Internationalization Sponsorship Program as the route for funding the work, which is the honest answer to who pays.

Editorial conclusion

Front-end engineers shipping Simplified or Traditional Chinese should read the clreq layout requirements before designing line breaking, punctuation, or ruby behaviour, and should file gap reports for browser bugs they hit. Teams looking for a fix-it library, a font bundle, or a drop-in internationalisation toolkit should skip this project. Verify first that the relevant section of the editor's draft matches the behaviour of the browsers you actually target, since the document is a requirements text and the last push was on 2026-09-16.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. w3c/clreq on GitHub