没有不值得去解决的问题,也没有不值得去学习的技术!

A Tour of Go Multilingual Translation: All 103 zh-CN Course Pages Are Ready, Completing the Main Content Translation Phase

Figure 4: Upstream source code confirms a total of 103 course pages; zh-CN ultimately reaches ready=103, pending=0, blocked=0

作者:

在

,

After the representative page calibration, protection rule adjustments, structural validation improvements, and multiple rounds of batch translation for regular pages, the A Tour of Go multilingual translation project has finally reached a very clear milestone:

  • ready=103
  • pending=0
  • blocked=0

That is, all 103 A Tour of Go course pages in the current upstream baseline have been fully translated into Simplified Chinese and have passed the project’s unified automated validation process.

It must be emphasized that this does not mean the Chinese version has been officially released yet.

What has been completed at this stage is the course content translation phase. The next phase will continue with pre-release global validation, including overall generation, browser rendering, public UI copy, page navigation, release artifacts, and production deployment boundaries.

However, as far as the course content itself is concerned, this phase is truly complete.

Figure 1: A Tour of Go Simplified Chinese course page after automated translation and unified validation
Figure 1: A Tour of Go Simplified Chinese course page after automated translation and unified validation

During this final wrap-up process, I encountered two highly representative cases in succession: one occurred during the inline code structure recovery phase, and the other during the complete link structure validation phase.

They both ultimately proved one thing:

A multilingual translation system cannot simply require the target language to strictly replicate the structural occurrence order of the source language. As long as a complete protected structure itself remains intact, an overall transposition to adapt to the natural word order of the target language should inherently be allowed.

These are the two most valuable discoveries from this final stage of the full-volume translation.


1. From Batch Trial Runs to True Full-Volume Translation

After verifying stability on the representative pages and the first few batches of regular pages, I continued at a pace of 10 pages per batch for the remaining pending pages.

Instead of manual page-by-page translation, this phase continued to use the established unified workflow:

Complete course page → GLM-5.2 full-page translation → save candidate → automated structural and page validation → ready

If it failed, the process continued with:

Limited full-page retry → if still failing, proceed to blocked

And blocked did not necessarily mean manual direct edits to the translation.

If the issue was later confirmed to stem from the recovery logic or the validator itself, the saved historical model responses could be directly reused for re-validation without needing to call the model again.

The status progression in this second half was very straightforward:

Stagereadypendingblocked
Batch 4 complete55480
Batch 5 complete65380
Batch 6 complete75280
Batch 7 complete85180
Batch 8 complete9580
Last 8 pages complete10300

As we progressed, the first-pass success rate for regular pages became increasingly stable.

For example, all 10 pages in Batch 8 passed attempt-001 on the first try; the final 8 remaining concurrency pages also all passed on the first round.

However, before truly reaching 103 / 0 / 0, there were still two issues that could not simply be dismissed as “model translation failures” that needed to be resolved.


2. moretypes/18: The Model Didn’t Miss Translating Code, but the Recovery Logic Merged Two Code Structures

During Batch 5 processing, moretypes/18 underwent translation 3 consecutive times, ultimately yielding the same error each time:

inline code count mismatch: expected 9, actual 8

Looking at the surface result, it was easy to conclude:

GLM-5.2 missed an inline code structure three times in a row.

But upon further inspection of the three raw responses, I found the exact opposite to be true.

The source page contained a total of 9 inline codes:

  1. Pic
  2. dy
  3. dx
  4. (x+y)/2
  5. x*y
  6. x^y
  7. []uint8
  8. [][]uint8
  9. uint8(intValue)

All three model responses fully retained the 9 pairs of inline code protection markers, token_valid=true.

The actual problem stemmed from adjustments for natural Chinese word order.

The original text contained:

Plaintext
each `[]uint8` inside the `[][]uint8`

The model naturally translated this into something like:

Plaintext
为 `[][]uint8` 中的每个 `[]uint8`

That is, the two complete inline code structures underwent an overall transposition.

This was completely correct in itself.

At the same time, several other functions were output by the model as:

Plaintext
`(x+y)/2`、`x*y` 和 `x^y`

This is where the problem occurred.

The original normalizeInlineTokenBoundaries would search for protection markers sequentially according to the pair order in the source text.

When it searched for the subsequent []uint8 and [][]uint8, the search failed and the function exited early because these two pairs had swapped positions according to Chinese word order.

The result was:

The inline code boundary normalization that should have occurred for the preceding parts was not completed.

Consequently:

Plaintext
`(x+y)/2`、`x*y`

was ultimately recognized by the legacy present parser as a single program span.

Thus resulting in:

expected 9, actual 8

Figure 2: Transposition of complete inline code in moretypes/18 exposes a recovery boundary issue; after the fix, the original historical response passes re-validation
Figure 2: Transposition of complete inline code in moretypes/18 exposes a recovery boundary issue; after the fix, the original historical response passes re-validation

3. The Fix: Process Based on Actual Positions in the Response, Rather Than Assuming Source Order Never Changes

Since the current design inherently allows complete inline code pairs to transpose to adapt to target language word order, the recovery logic should adhere to the same principle.

The final modified algorithm no longer searches for all pairs serially according to the source order. Instead, it:

  1. Independently finds each valid opening / closing pair;
  2. Obtains their actual positions in the model response;
  3. Re-sorts them based on their actual positions;
  4. Determines whether ASCII space padding is needed based on true adjacency;
  5. Then uniformly performs boundary normalization.

At the same time, the original strict validation was not relaxed.

The following cases must still be rejected:

  • Missing tokens;
  • Duplicate tokens;
  • Mismatched opening and closing markers;
  • Crossing pairs;
  • Modified pair contents.

In other words:

What was relaxed is the “order of appearance for complete structures,” not the structural integrity itself.

After the fix, instead of calling GLM-5.2 again, I directly fed the 3 saved historical responses from moretypes/18 back into the recovery and unified candidate validation.

As a result, all three were able to recover the 9 inline codes and pass validation.

Then, through the formal translate revalidate-response process, I selected the earliest attempt-001 recovery candidate, ultimately turning:

blocked → ready

And not a single word of the model’s original response was changed.

This is exactly the capability I wanted this project to have:

If a failure stems from the translation infrastructure rather than the translation itself, fix the infrastructure and let the original historical responses re-enter unified validation, instead of manually tampering with the results just to get a page to “pass”.


4. methods/17: Encountering “Complete Structure Transposition” a Second Time

By Batch 7, a very similar problem occurred again.

The original content of methods/17 included two links:

Plaintext
[[/pkg/fmt/#Stringer][`Stringer`]]

And:

Plaintext
[[/pkg/fmt/][`fmt`]]

The English expression roughly translates to:

Plaintext
Stringer defined by fmt

While the natural Chinese expression clearly leans toward:

Plaintext
由 fmt 包定义的 Stringer

Therefore, on the third attempt, the model swapped the positions of the two complete link structures.

The source order seen by the old validator was:

/pkg/fmt/#Stringer → /pkg/fmt/

But the order in the candidate translation became:

/pkg/fmt/ → /pkg/fmt/#Stringer

Thus it reported:

link targets mismatch at index 1

Initially, it looked like:

The model incorrectly changed /pkg/fmt/#Stringer to /pkg/fmt/.

But after checking the complete structures, I found that it did not.

The model actually still maintained:

  • /pkg/fmt/#Stringer corresponding to Stringer
  • /pkg/fmt/ corresponding to fmt

Neither link target was lost, neither was modified, and neither was paired with the wrong link text.

The two complete links simply swapped positions for Chinese word order.

Figure 3: Two complete links in methods/17 transpose according to Chinese word order; after correcting the validation logic, the historical response is successfully recovered
Figure 3: Two complete links in methods/17 transpose according to Chinese word order; after correcting the validation logic, the historical response is successfully recovered

5. Cannot Simply Change Link Targets to an Unordered Set Comparison

There was another point requiring extra care in this fix.

Since two links can transpose entirely, could I simply change:

link target

into an unordered set comparison?

No.

Because merely confirming:

  • /pkg/fmt/#Stringer exists;
  • /pkg/fmt/ exists;

was not enough.

If the model incorrectly generated:

  • /pkg/fmt/ → Stringer
  • /pkg/fmt/#Stringer → fmt

Then although neither target was missing, they had already been mismatched.

Therefore, the new validation logic does not use a simple target set; instead, it factors in the complete link identity.

For links containing a protected inline code payload, it uses something like:

target + link 内 inline-code payload 多重集合

as the complete link identity, and then performs an unordered comparison.

This simultaneously satisfies two requirements:

Allowing:

Overall transposition of complete link structures.

But still rejecting:

Cross-mismatching between targets and link text.

Meanwhile, regular links without protected payloads still retain their original order validation; not all links were unconditionally converted to unordered comparisons.

After the fix, the attempt-003 historical response for methods/17 directly passed the unified candidate validation.

Subsequently, the formal revalidate-response was similarly used for recovery:

blocked → ready

This entire process also did not call GLM-5.2 again.


6. These Two Issues Actually Point to the Same Design Principle

moretypes/18 and methods/17 appear on the surface to be two completely different problems.

One involves inline code:

Plaintext
[]uint8
[][]uint8

The other involves complete links:

Plaintext
Stringer
fmt

But the root cause behind them is identical:

Source language structural order cannot be mistaken for a semantic constraint that the target language must preserve.

Initially, to ensure translation safety, we continually added Protected Tokens, structural signatures, and various validations.

These protections themselves are certainly valuable.

But when validation rules start to assume:

If A appears before B in English, then A must always appear before B in Chinese.

The protection mechanism itself can create new false positives.

The principle ultimately formed from these two fixes is:

Structural identity must be preserved, internal binding relationships within structures must be preserved, but complete structures are allowed to be rearranged according to the natural word order of the target language.

This is more accurate than simply “relaxing order restrictions”.

We did not lower structural safety requirements; instead, we are distinguishing between:

  • What constitutes a truly indestructible structure;
  • What is merely an incidental arrangement brought about by source language expression order.

This is also very important for adding Japanese or other languages in the future.


7. The Final 28 Pages Became Very Stable

After resolving these two boundary issues, the progress on remaining pages accelerated significantly.

In Batch 6, methods/6 only had a missing Protected Token on the first attempt, and passed on the second; this is a normal model retry scenario.

The 10 pages in Batch 8:

  • methods/18
  • methods/19
  • methods/21
  • methods/22
  • methods/23
  • methods/25
  • methods/26
  • generics/2
  • generics/3
  • concurrency/1

All passed attempt-001 on the first try.

The final 8 remaining pages:

  • concurrency/2
  • concurrency/3
  • concurrency/4
  • concurrency/5
  • concurrency/6
  • concurrency/8
  • concurrency/9
  • concurrency/10

Similarly all passed on the first round.

At this point, the status officially reached:

  • ready=103
  • pending=0
  • blocked=0

Final commit:

584ce7d6f22c68f983d4199deee8f36aec450be5

And it has been pushed to the project repository.


8. Are 103 Pages Really All the Pages?

After completing 103 / 0 / 0, I suddenly thought of another question:

A Tour of Go also contains #appengine: conditional content, so could the actual number of course pages exceed 103?

This question warranted careful verification.

Because if the status file itself was built from an incomplete set of pages, then:

pending=0

would not prove that everything was truly translated.

So I re-verified the page topology directly from the currently fixed official upstream source code.

Current upstream baseline:

master@e11dacba76c5aae474746e9eedee19693f492803

A Tour of Go uses 7 .article files:

  • basics.article
  • concurrency.article
  • flowcontrol.article
  • generics.article
  • methods.article
  • moretypes.article
  • welcome.article

After re-counting the top-level Sections, the result was:

  • Regular top-level Sections: 101
  • #appengine conditional top-level Sections: 2
  • Total: 103

Both conditional top-level Sections are located within welcome.article:

  • Go offline (optional)
  • The Go Playground

Although #appengine: conditional content also exists in concurrency.article and flowcontrol.article, it is merely conditional content within existing pages and does not form new top-level Sections, so it does not increase the number of course pages.

In other words:

101 + 2 = 103

Only now has it been truly confirmed at the official source code level that:

The current ready=103 indeed corresponds to the complete set of A Tour of Go course pages under the current upstream baseline, rather than just having processed an incomplete status table.

Figure 4: Upstream source code confirms a total of 103 course pages; zh-CN ultimately reaches ready=103, pending=0, blocked=0
Figure 4: Upstream source code confirms a total of 103 course pages; zh-CN ultimately reaches ready=103, pending=0, blocked=0

9. What Has Been Completed is the “Translation Phase”, Not “Release Completion”

At this point, the course content translation within the first phase of the A Tour of Go multilingual translation project is complete.

It can now be explicitly confirmed that:

  • All 103 course pages exist;
  • All 103 pages have completed zh-CN translation;
  • All pages have gone through the same Protected Token recovery process;
  • All pages have been parsed by present;
  • All pages have undergone structural comparison;
  • All candidates have passed unified page validation;
  • pending=0;
  • blocked=0;
  • The workspace is clean;
  • The final translation results have been committed and pushed.

However, the project is not yet ready for official release.

What follows is another phase:

zh-CN pre-release global validation.

Its focus will no longer be “whether a specific page was translated successfully”, but rather whether the entire site, as a complete product, is ready for release, for example:

  • Final build results for the 103 pages;
  • Page navigation and course topology;
  • Actual browser rendering;
  • Public UI copy;
  • Links and static resources;
  • Go examples on the right side;
  • Single-language build artifacts;
  • Production environment deployment method;
  • Production boundaries for the local /socket code execution interface;
  • Overall regression before final release.

Therefore, I will not temporarily refer to the current status as “the Chinese version is complete”.

A more accurate statement is:

All 103 A Tour of Go Simplified Chinese course pages have been fully translated and have entered ready; the course content translation phase is officially over.

The next step is to begin the pre-release global validation.


10. Phase Summary

When I first started designing this project, I did not want the end result to merely be:

Calling a large model to batch replace English with Chinese.

The truly difficult part has always been:

How to allow the model to utilize its normal Chinese expression capabilities, while simultaneously proving that key content like code, links, directives, and page structures have not been broken.

And after actually running through all 103 pages, this point became even more confirmed.

If protections are too few, the model might break the structure.

But if protections and validations are too rigid, normal Chinese word order adjustments will be flagged as errors.

moretypes/18 and methods/17 proved this exactly from the recovery phase and validation phase, respectively.

The end result is not “Chinese must obey English order”, but rather a set of clearer boundaries:

Content that is truly untranslatable and indestructible must be strictly preserved; between complete protected structures, however, reordering for natural expression in the target language should be allowed.

Now, all 103 pages under the current upstream baseline have gone through this process.

ready=103.

pending=0.

blocked=0.

The course content translation phase can finally come to a close here.

关于作者 · 持续学习与技术实践

我是一名拥有 15 年以上开发经验的技术从业者,自 2013 年起持续运营个人技术博客,记录工作与个人项目中遇到的真实问题,以及解决问题过程中的探索、实践和思考。

除了技术写作,我也在持续开发和维护自己的独立项目,探索新技术和新工具在实际场景中的应用。我始终相信,没有不值得去解决的问题,也没有不值得去学习的技术。

如果这篇文章对你有所帮助,欢迎浏览博客中的其他文章,也欢迎交流技术经验与想法。

关于我  ·  GitHub  ·  邮件联系