Skip to content

zh: link newsletters 203+ to their Chinese translations - #2931

Open
bittomhan wants to merge 6 commits into
bitcoinops:masterfrom
bittomhan:update-ref
Open

bittomhan wants to merge 6 commits into
bitcoinops:masterfrom
bittomhan:update-ref

Conversation

@bittomhan

@bittomhan bittomhan commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes #2383.

Chinese translations of newsletters #203 onward linked to the /en/ page even when a /zh/ translation already existed. This PR points them at the Chinese page, and corrects the anchors that would otherwise land on the wrong place.

Two kinds of edits are needed, because switching the language segment alone is not enough:

  1. Language segment — /en/newsletters/ → /zh/newsletters/ for 196 references. The target Chinese page exists in every case.
  2. Anchors — 42 references whose fragment does not exist on the target Chinese page.

If only step 1 were done, those 42 links would render and navigate, but land at the top of the page instead of the referenced item — a silent half-fix. They are kept in a separate commit so the two concerns can be reviewed independently.

Size

  • 108 files, +448 / −447
  • 5 commits
commit content size
d3f6fe38 #204–#228, authored earlier but never merged 25 files, +215/−215
be8ee294 language segment only 196 refs, 77 files
1f61d2f5 anchor alignment 40 refs, 23 files
dc0ff28a BLS heading id matched to the English spelling 2 refs
6b21643d merge of upstream/master —

d3f6fe38 predates this work: it covers #204–#228 with the same two kinds of edits (41 references, plus 174 anchor reforms that make the Chinese item ids match the English ones). It was never merged, so it travels with this branch rather than being redone.

How the anchors were chosen

Two cases, both verified against the id the target page actually emits in a local jekyll build:

  • The Chinese page keeps the English comment anchor. Most pages do (396 of 427). The reference can simply copy the English fragment.
  • The page renders only a Chinese heading id. Then the reference uses that id, e.g. #conclusion → #结论 on the 2020 year-in-review.

Three specific problems were found and fixed along the way:

Anchor changes

#2383 also asks that future translations be able to reuse the anchors we already have, which is only true if the Chinese page emits the same id as the English page for the same item. This PR therefore also aligns item ids, and that changes some anchors. Measured by diffing the ids in the built HTML before and after:

  • 24 of the 428 Chinese newsletter pages change ids: 91 ids replaced, 92 added.
  • 85 of the 92 new ids are identical to the id the English page emits for the same item — e.g. #musig2 → #musig2-security-vulnerability, #rollup → #validity-rollups-research, and the two degraded #n1 / #n8 → #experimentation-with-silent-payments / #btcpay-server-1-5-1.
  • Two move the other way: #news becomes #新闻 on compat: Mycelium on Android supports sending to P2WPKH and P2SH #216 and Plugins: auto-anchor: use smallest match #218, because those pages had an untranslated ## News heading that is now translated. This is the only case where a Chinese id moves away from the English one.
  • Scanning every href in the built site afterwards: 0 fragments pointing at a Chinese newsletter resolve to a missing id.

The cost is that a bookmark to one of the 91 old ids now lands at the top of the page. Keeping them alive is possible by adding an empty <a id="old-id"> next to each new one, but that is 91 lines of marker noise on 24 pages for ids that were mostly malformed to begin with (n1, n8, duplicated suffixes), so this PR does not do it. Happy to add them if reviewers prefer.

Not touched by this PR

Three files below #203 are touched, each for a specific reason rather than as part of the bulk conversion: #72 (adds the {:#x-only-pubkeys} marker the translation had dropped), #180 (two references retargeted to the Chinese heading ids), and #198 (the degraded n8 id).

Verification

  • bundle exec jekyll build passes (exit 0) in a clean build.
  • Automated scan of all 427 Chinese newsletters against the built HTML: 0 broken anchors, 0 dead links, down from 196 + 35 before the change.
  • Every one of the 233 edited lines was traced back to the corresponding reference in the English source; 224 match the English fragment exactly, the remainder are documented above.

Notes for the reviewer

  • Reviewing commit by commit is easier: be8ee294 is a mechanical one-line-per-reference change; the anchor commit is where judgement was involved.
  • Five references use a Chinese heading id instead of the English fragment because the target page does not generate that English id (e.g. #preparing-for-taproot-1-bech32m-sending-support → #准备-taproot-1bech32m-发送支持). Making them identical would require adding comment anchors to those five pages, which would in turn break references already pointing at the Chinese ids.
  • Going forward, a new translation can usually copy the English link and only switch the language segment, since most Chinese pages keep the English comment anchors.

Chinese newsletters 203+ referenced /en/ pages for issues that already
have a /zh/ translation (issue bitcoinops#2383). Only the language segment is
retargeted: 196 references.

Two are intentionally left on /en/:
- a quoted tweet in bitcoinops#200, whose text is verbatim third-party content
- bitcoinops#5, where the /en/ anchor is already dead upstream; changing the
  language segment would not fix anything
Fix 40 references across 23 files. Each new fragment is verified against
the id the target Chinese page emits in a local jekyll build, and each
edit is located by full link string rather than line number -- an earlier
pass mis-assigned four anchors in bitcoinops#231 through line drift.

Four groups:
- term names replaced by the heading they belong to (#musig2, #rollup,
  #ln-penalty, #btcd-lnd, #bip324)
- <!--n1-->/<!--n8--> placeholder comments replaced by the full slug
- the {:#x-only-pubkeys} marker restored in bitcoinops#72
- bitcoinops#231 [news214 sp] repointed to #updated-silent-payments-pr; the English
  original does carry this reference, only its fragment is wrong
The Chinese source wrote the comment anchor as 'bitcoincompatible' while
the English page emits 'bitcoin-compatible'. Only the heading and bitcoinops#231's
reference use it, so align both sides and keep the reference identical to
the English original instead of translating the fragment.
@bitschmidty

Copy link
Copy Markdown
Contributor

The English original points at the same missing anchor, so this is an upstream issue rather than a translation one.

It seems https://bitcoinops.org/en/newsletters/2018/06/26/#first-optech-workshop is indeed correct?
And there is a zh: https://bitcoinops.org/zh/newsletters/2018/06/26/#%E7%AC%AC%E4%B8%80%E6%AC%A1-optech-%E5%B7%A5%E4%BD%9C%E5%9D%8A

It seems some of the anchors have changed which is ok internally it seems but if anyone has bookmarked the old anchors, they will end up on that page without the anchor. I think this is ok but just wanted to bring it up.

Also, I think you touch some of @hulatown 's translated pages so tagging him here in case he has any feedback.

@bittomhan

Copy link
Copy Markdown
Contributor Author

Thanks — you're right on all three points, and I've corrected the description.

#5 is not an upstream problem. https://bitcoinops.org/en/newsletters/2018/06/26/#first-optech-workshop resolves correctly: id="first-optech-workshop" is on that page, and the Chinese page of the same newsletter has its own id, #第一次-optech-工作坊, exactly as you linked. The sentence you quoted was wrong. At one point I had rewritten that reference to /zh/, where #first-optech-workshop does not exist, and I kept the justification after reverting the link. The file is not touched by this PR at all — #2383 scopes the change to #203 onward, and #5 is outside it. It should have been described as out of scope rather than as a known-bad anchor.

On the anchors that changed, here is the count, measured against the built HTML rather than the source:

  • 24 of the 428 Chinese newsletter pages change ids, 91 ids in total.
  • 85 of the 92 replacement ids are identical to the id the English page emits for the same item — e.g. #musig2 → #musig2-security-vulnerability, #rollup → #validity-rollups-research, and the degraded #n1 / #n8 → #experimentation-with-silent-payments / #btcpay-server-1-5-1. That alignment is the point: it is what makes Chinese translation link updates #2383's third request work, so a future translation can copy the English fragment and only switch the language segment.
  • Two ids move the other way: #news becomes #新闻 on compat: Mycelium on Android supports sending to P2WPKH and P2SH #216 and Plugins: auto-anchor: use smallest match #218, because those two pages had an untranslated ## News heading that is now translated. That is the only case where a Chinese id moves away from English.
  • I re-scanned every href in the built site afterwards: 0 fragments pointing at a Chinese newsletter resolve to a missing id.

So the cost is exactly what you describe — a bookmark to one of the 91 old ids lands at the top of the page. I agree that is acceptable. If you would rather keep them alive, I can add empty <a id="..."> anchors next to the new ids; it costs 91 lines of marker noise on 24 pages for ids that were mostly malformed to begin with (n1, n8, duplicated suffixes), so my preference is to leave it as is.

@hulatown — only two of the files touched here were originally added by you (#252 and #253, 2023-05-24 and 2023-05-31). The edits there are language segment and anchor only, no wording changes. Happy to revert anything that looks off.

I've also added an "Anchor changes" section to the description with these numbers, and corrected the note about #5.

@bitschmidty bitschmidty left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems the older "2022” commit also changes some wording, not just links and anchors.

I'm ok either way on these. If they're intentional, we can keep them, lmk @bittomhan

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Chinese translation link updates

2 participants