Re: Subject: [RFC] docs/zh_TW: defining a maintainable scope for the Traditional Chinese translation

On Sun, Sep 06, 2026 at 04:21:24AM +0800, 葉宸佑 wrote:

Hi all,

Now that zh_TW has maintainers again, the next question is what we can
credibly promise to keep current.  The tree holds 97 files, and a survey
of them says: not all of them.  I would rather narrow the scope openly
than leave readers to find out which pages lie to them.

Yes.

This follows on from Jon's question in the contact-block cleanup thread
[1], where I said the wider question of what to do with the stale
translations deserved its own discussion.

In general, my personal preference is to completely eliminate this mess,
then reorganize the structure and align the English one.

2. Translations whose original moved out from under them
========================================================

This is the part that worries me most, because it is invisible to a
reader and to most tooling: the translation looks fine, but the English
document it mirrors has been relocated, so nobody working on the English
side has any reason to look at us.

  ==================================  =========================================
  zh_TW file                          English original now lives at
  ==================================  =========================================
  admin-guide/security-bugs.rst       process/security-bugs.rst
  process/magic-number.rst            staging/magic-number.rst
  dev-tools/gdb-kernel-debugging.rst  process/debugging/gdb-kernel-debugging.rst
  arch/arm/Booting                    arch/arm/booting.rst
  ==================================  =========================================

The moves upstream were:

  2023-03-05  Documentation/security-bugs: move from admin-guide/ to process/
  2024-06-24  Docs: Move magic-number from process to staging
  2024-12-09  Documentation: move dev-tools debugging files to
process/debugging/

All three translations still sit in the old location, and all three are
still linked from a zh_TW index, so a reader is pointed at a file that
mirrors a document which has since been filed somewhere else.

Two more translate content that was restructured rather than moved:

  - IRQ.txt renders an old version of core-api/irq/index.rst.  That file
    is now a twelve-line toctree; the prose it translates lives in
    core-api/irq/concepts.rst.
  - io_ordering.txt is in the same position relative to
    driver-api/io_ordering.rst.

Six files carry no :Original: field at all, so
tools/docs/checktransupdate.py cannot tell what they mirror and skips
them silently:

  index.rst, arch/index.rst, disclaimer-zh_TW.rst,
  dev-tools/sparse.rst, admin-guide/clearing-warn-once.rst,
  admin-guide/cpu-load.rst

There is a second reason this matters.  Where the :Original: marker is
missing, checktransupdate.py falls back to comparing author dates, which
means any mechanical tree-wide pass over the translations resets the
apparent baseline: after such a pass the tool reports those files as up
to date, because the translation is newer than every English change.  I
ran into this while preparing this survey -- measured on top of my own
pending contact-block cleanup, which touches most of the tree, the
number of stale files drops from 51 to 2.  None of that staleness went
away; it just stopped being visible.  A tree without :Original: fields
cannot be measured reliably at all.

Whatever else we decide, I would like to fix these two classes first:
move the misplaced files so they mirror the current English layout, and
give every translation an :Original: field.  That is what makes the rest
of the tree checkable at all.

My idea is: If the current translation quality is acceptable and it's
not troublesome to move it, I think we can just move it. On the
contrary, if the translation is significantly behind, there is no need
to go through all the trouble, just delete them.

Quoting Dongliang:

| But for the current situation of zh_TW, re-translation may be more
| efficient. -- Dongliang [ref]

3. How far behind the rest is
=============================

Using tools/docs/checktransupdate.py over all 87 .rst files:

  ============================  =====
  Upstream commits not applied  Files
  ============================  =====
  1-3                              30
  4-9                              13
  10-19                             7
  20 or more                        1
  ============================  =====

51 files are behind, by 245 commits in total.  The other 36 are level
with their originals only because those originals have not changed
either; nobody is actively keeping any of them current.

The process/ series currently on the list accounts for 66 of those 245
commits and brings all of process/ to zero.

Yup, let's do this part later.

And after process/, I'd like to do that part "Working with the
development community".

Excluding it, the worst remaining cases are:

  ===================================  ==============
  File                                 Commits behind
  ===================================  ==============
  admin-guide/mm/damon/usage.rst                   33
  filesystems/index.rst                            17
  arch/arm64/elf_hwcaps.rst                        13
  admin-guide/index.rst                            12
  dev-tools/index.rst                              11
  admin-guide/mm/damon/lru_sort.rst                10
  ===================================  ==============

Tricky?

4. Documents no reader can reach
================================

18 files are not referenced from any toctree.  Sphinx still renders them,
but nothing links to them, so they are unreachable unless you already
know the URL:

  - nine pre-RST files kept in the old plain-text format: IRQ.txt,
    io_ordering.txt, arch/arm/Booting, arch/arm/kernel_user_helpers.txt,
    arch/arm64/{booting,legacy_instructions,memory,silicon-errata,
    tagged-pointers}.txt
  - filesystems/ (5 files, one of which is a tenth plain-text file,
    sysfs.txt) and cpu-freq/ (4 files), which have index.rst files of
    their own that the top-level zh_TW index never links to

disclaimer-zh_TW.rst is also outside the toctree, but deliberately so:
it is marked :orphan: because it is included rather than linked.  It is
not counted above.

So I would like to restate my point again: Completely reorganizing these
structures is obviously much more convenient than handling them one by
one.

5. Per-area summary
===================

  ==============  =====  ===========  ======  ==============
  Area            Files  Unreachable  Behind  Commits behind
  ==============  =====  ===========  ======  ==============
  process            27            0      14              66
  arch               28            7      12              35
  admin-guide        23            0      15              99
  dev-tools           6            0       5              16
  filesystems         5            5       3              21
  cpu-freq            4            4       1               1
  top level           4            2       1               7
  ==============  =====  ===========  ======  ==============

Within those, admin-guide/mm/damon (5 files) accounts for 55 of
admin-guide's 99, and arch/arm64 (10 files) for 23 of arch's 35.

6. Proposal
===========

I would rather do one area properly than all of them badly, so I propose
we start narrow and grow the supported set as people show up.

True. True.

Step 1, now: process/ becomes the supported set.

  27 files, no unreachable documents, and the pending series already
  brings it to zero commits behind.  It is also what a Taiwanese reader
  starting kernel work reads first.  Committing to keep this current is a
  promise we can keep today.

  As part of this, fix the structural problems in section 2: relocate the
  misplaced translations and add the missing :Original: fields, so
  checktransupdate covers the whole tree.

Yes.

Step 2, next: the 70 files outside process/ are marked as not currently
maintained.

  That is most of the tree, so to be explicit about what it means: the
  files stay where they are and readers can still find them, but each one
  says plainly that it is not kept in sync and points at the English
  original.

  Rather than inventing a mechanism, reuse the one the tree has: a short
  notice included at the top of the file, the way disclaimer-zh_TW.rst is
  included today.  If people would rather leave the files untouched, the
  same information could live in the index instead.

I'm fine with both. However, the former might be clearer and more
understandable for the readers. If it is only included in the index,
some readers might not bother to look at it.

  Areas would move out of this set as they find someone to look after
  them, rather than being promised anything up front.

Step 3, to decide here: the nine unreachable plain-text files.

  They are unreachable, they use a format the rest of the tree left
  behind years ago, and two of them describe content that no longer
  exists upstream in that shape.  I lean towards removing them: nothing
  links to them, so no reader loses anything.

Agreed, let's remove them.

  filesystems/sysfs.txt is in the same old format but is reachable from
  filesystems/index.rst, so I have left it out of this step.

Open question: filesystems/ and cpu-freq/ (9 files) are unreachable only
because the top-level index never links them.  We can link them and mark
them unmaintained, or drop them.  I lean towards linking, since the
translations themselves are not in bad shape.

Fine. That's OK.

7. What I am not proposing
==========================

I am not proposing to touch zh_CN, and I am not proposing to remove
anything a reader can currently reach, apart from the nine plain-text
files in step 3.  I am also not asking anyone to review Chinese text; the
decisions here are about scope, not translation quality.

;-o  ;-)

Sequencing: the two pending zh_TW series should land first, so this
discussion is not competing with them.  What I would like out of this
thread is

agreement on the shape 

So ditto:

If the current translation quality is acceptable and it's not
troublesome to move it, I think we can just move it. On the contrary, if
the translation is significantly behind, there is no need to go through
all the trouble, just delete them.

But hey, this is just my personal opinion.

after which I will send the relocations, the :Original: fixes, and the notices as separate series.

Sure.

Thanks.