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

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

[葉宸佑]

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.

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.

This mail is the survey plus a proposal.  Comments welcome, particularly
from the zh_CN maintainers: most of these files were converted from
zh_CN, so some of the same questions apply there.

All figures below are measured against mainline, so they can be
reproduced; where a pending series changes them, I say so.

[1] https://lore.kernel.org/all/87cxve80yy.fsf@trenco.lwn.net/

1. How the tree got here
========================

zh_TW was added in July 2021 as a conversion of zh_CN, and most of it has
not been touched since:

  - 24 of 97 files have exactly one commit: the import.
  - Most of the remaining commits are two tree-wide mechanical passes: a
    character conversion in late 2023, and link/typo fixes.
  - The listed maintainer address stopped answering zh_TW mail about two
    years ago, which is what left the tree in this state.

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.

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.  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
  ===================================  ==============

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.

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.

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.

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.

  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.

  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.

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.

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, after which I will send the
relocations, the :Original: fixes, and the notices as separate series.

Thanks,
Chen-Yu Yeh

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

[Weijie Yuan]

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 <45167b0a-4c60-43a4-9c3d-b8ddcbb8679c@hust.edu.cn>



> 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.

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

[葉宸佑]

> 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.

I understand the appeal, and for some files I think you are right. But
I would like to separate two things that are getting mixed together:
relocating a file is cheap and mechanical, while deciding to delete one
is neither, and the two do not have to be decided at the same time.

The four relocations in section 2 are the cheap case: the files are
reachable, they are not the worst offenders, and moving them is a
rename plus an :Original: fix. I would rather just do that and revisit
their content later.

For deletion, my hesitation is that it is the one decision here we
cannot walk back. Marking a file unmaintained can be undone the moment
someone turns up to look after it; deleting it means the next person
starts from nothing. Right now zh_TW has one native speaker, so
"re-translate instead" is only more efficient if the re-translation
actually happens.

So I would suggest: deletion by exception rather than by rule. Rather
than "significantly behind means delete", we name the specific files we
think are beyond saving and say why. If you would like to propose a
list, I am happy to look at each one -- I suspect we would agree on
more of them than this exchange makes it sound.

> Tricky?

The six worst are mostly two clusters: admin-guide/mm/damon (5 files,
55 commits between them) and arch/arm64. Those are exactly the files I
would expect a Taiwanese reader to skip in favour of the English, so
they are strong candidates for whatever we decide "unmaintained" means
-- and, if you want to make the case, for deletion.

> However, the former might be clearer and more understandable for the
> readers.

Agreed, the notice belongs in the file. I will do it that way.

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

Good -- that is the section of the index that matters most after
process/ itself.

Dongliang: Weijie quoted you above on re-translation being more
efficient. That was in a different context, so I would rather not
assume it carries over -- what is your view on delete-versus-mark for
the files outside process/?

Thanks,
Chen-Yu Yeh

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

[Weijie Yuan]

On Wed, Sep 09, 2026 at 05:40:44AM +0800, 葉宸佑 wrote:
> > 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.
> 
> I understand the appeal, and for some files I think you are right. But
> I would like to separate two things that are getting mixed together:
> relocating a file is cheap and mechanical, while deciding to delete one
> is neither, and the two do not have to be decided at the same time.

Reasonable. Agreed.

> The four relocations in section 2 are the cheap case: the files are
> reachable, they are not the worst offenders, and moving them is a
> rename plus an :Original: fix. I would rather just do that and revisit
> their content later.

Agreed.

> For deletion, my hesitation is that it is the one decision here we
> cannot walk back. Marking a file unmaintained can be undone the moment
> someone turns up to look after it; deleting it means the next person
> starts from nothing. Right now zh_TW has one native speaker, so
> "re-translate instead" is only more efficient if the re-translation
> actually happens.

Yeah, I thought of this point before, so yes, I agree.

Modifying existing contents is way more atractive to new contributors
than waiting them to start from scratch.

I admit that my initial insistence that aims to keep the directory too
clean was not conducive to our future development.

Then let's leave some less perfect aspects to attract others to get
involved.

> So I would suggest: deletion by exception rather than by rule. Rather
> than "significantly behind means delete", we name the specific files we
> think are beyond saving and say why. If you would like to propose a
> list, I am happy to look at each one -- I suspect we would agree on
> more of them than this exchange makes it sound.

Sure, I'd love to look deeper into specfic files. And take them for
later discussion. A discussion without specific documents is indeed a
bit vague. My bad.

> > Tricky?
> 
> The six worst are mostly two clusters: admin-guide/mm/damon (5 files,
> 55 commits between them) and arch/arm64. Those are exactly the files I
> would expect a Taiwanese reader to skip in favour of the English, so
> they are strong candidates for whatever we decide "unmaintained" means
> -- and, if you want to make the case, for deletion.

Yes, I guess nobody would read this? So I'm fine with both decision.

> > However, the former might be clearer and more understandable for the
> > readers.
> 
> Agreed, the notice belongs in the file. I will do it that way.

OK, if no other ideas or objections, let's do so.

> > And after process/, I'd like to do that part "Working with the
> > development community".
> 
> Good -- that is the section of the index that matters most after
> process/ itself.
> 
> Dongliang: Weijie quoted you above on re-translation being more
> efficient. That was in a different context, so I would rather not
> assume it carries over.

True. After your detailed analysis and our discussion, I think a simple
re-translation is clearly not comprehensive enough.

Thanks!