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

A Tour of Go Multilingual Translation Project: First 10 General Pages Move From 2 Blocked to All Ready

Figure 2: The first batch of 10 ordinary pages all enter ready status after the test run and process calibration

作者:

在

,

In the previous phase, I was in no rush to batch-translate A Tour of Go.

The reason is simple: the real difficulty of this project was never about “getting an LLM to translate English into Chinese.” Rather, it was about how to strictly preserve the present syntax, inline code, links, .play directives, emphasis structures, and other content that must not be arbitrarily rewritten during full-page translation.

After completing the translation and calibration of 7 representative pages, the project had already covered various typical structures such as generics, inline code, links, preformatted code, emphasis structures, exercise pages, and .play.

Therefore, I decided to officially move on to the next phase:

Instead of specifically picking special pages, continuously test-run 10 ordinary pending pages.

The pages selected for this batch are:

Plaintext
basics/4
basics/5
basics/6
basics/7
basics/8
basics/9
basics/10
basics/11
basics/12
basics/13

I originally thought this round would mainly verify process stability.

Unexpectedly, these 10 pages instead helped me discover and resolve several highly valuable process issues.

1. First Round Results: 8 ready, 2 blocked

After executing these 10 pages in sequence according to the existing formal single-page translation process for the first time, the results were as follows:

PageFinal StatusAttempts
basics/4blocked3
basics/5ready1
basics/6blocked3
basics/7ready1
basics/8ready1
basics/9ready1
basics/10ready1
basics/11ready1
basics/12ready2
basics/13ready1

That is:

Plaintext
ready   = 8
blocked = 2
pending = 0

On the surface, 80% of the pages were completed.

However, the reasons for the two blocked pages were completely different.

For basics/4, the first three failures were not even translation failures at all.

2. Network Errors Can Also Exhaust the Three Formal Translation Attempts

All three attempts for basics/4 encountered similar errors:

Plaintext
network: Post https://open.bigmodel.cn/...
dial udp ...
socket: operation not permitted

In other words, the requests never actually reached GLM-5.2.

However, the existing formal process only checks “how many attempts have been executed,” and after three attempts, it still marked the page as:

Plaintext
blocked
attempts=3

This exposed an issue.

In a production environment, DNS, network connection, and temporary infrastructure failures can all happen.

If three network failures permanently consume the three translation attempts, then a page that was never actually translated by the model would be misjudged as “consecutive model translation failures.”

Therefore, a formal network failure recovery command was added this time:

Plaintext
translate recover-network

It does not simply reset attempts to zero.

The recovery must be able to prove from the historical audit records that:

  • The page is currently blocked;
  • The most recent three-attempt retry window consisted entirely of network errors;
  • No valid model response was received in any attempt;
  • There were no structural validation failures;
  • There were no translation failures that occurred after receiving an HTTP 200.

Only after meeting these conditions is an explicit recovery allowed.

The historical records are permanently retained.

For example:

Plaintext
attempt-001
attempt-002
attempt-003
network-recovery-001.json
attempt-004
attempt-005
attempt-006

The previous failure records will not be overwritten.

3. Another Issue Discovered: “Each CLI Invocation” Cannot Be Treated as a New Set of Three Attempts

While initially implementing the network recovery mechanism, a rather subtle issue was also discovered.

If the logic were written as:

Each time translate run is executed, allow up to three more attempts starting from the next attempt.

Then the following could occur:

Plaintext
First run:
attempt-001 fails
↓
Program interrupts

Second run:
attempt-002
attempt-003
attempt-004

This way, even without performing any recovery operation, the page would actually receive 4 formal attempts.

If repeatedly interrupted, the number could continue to increase.

Therefore, the “historical attempt number” and the “current retry window” were later completely separated.

The current rule is:

Plaintext
Initial window: 001–003

First valid recovery:
004–006

Second valid recovery:
007–009

Within the same window, no matter how many times the command is executed, only the remaining attempts in that window can be used.

Only an explicitly executed recovery that passes the eligibility check can open the next window.

Although this is not a translation quality issue, it is a very important state safety concern for actual batch runs in the future.

4. After Recovering basics/4, Real Translation Failures Were Finally Encountered

After completing the network recovery mechanism, I recovered and reran basics/4.

As a result, the new three attempts all actually received HTTP 200 responses from GLM-5.2, but still failed:

Plaintext
attempt-004
Protected tokens missing, duplicated

attempt-005
Tokens all correct
But font span count mismatch

attempt-006
All 5 protected tokens lost

This time, basics/4 truly became a translation failure page.

The most noteworthy attempt to analyze is attempt-005.

The original text had the sentence:

Plaintext
Notice that the type comes _after_ the variable name.

The model translated it into something like:

Plaintext
注意,类型位于变量名_之后_。

It looks like _之后_ is still present.

However, present’s parsing of emphasis syntax depends on boundaries.

Because _之后_ is directly adjacent to the Chinese text “变量名”, it was ultimately not parsed correctly as italics.

In other words:

The structural characters still being present does not mean the structural semantics are still intact.

5. Emphasis Structures: No Longer Letting the Model Maintain _ and * Itself

Previously, dangerous structures like inline code already had a protection mechanism, but italics and bold still mainly relied on the model to maintain them itself:

Plaintext
_after_

This time, I shifted to “protecting structural boundaries while continuing to translate the internal text.”

Conceptually, it is equivalent to:

Plaintext
<italic start marker>after<italic end marker>

Where:

Plaintext
after

Can still be translated into:

Plaintext
之后

But the opening and closing boundaries are handled by the program.

If the model outputs:

Plaintext
变量名<italic start marker>之后<italic end marker>。

The recovery phase will deterministically generate:

Plaintext
变量名 _之后_。

While also adding the boundary spaces required for present parsing.

After making the changes, I reran basics/4 in development mode.

The new attempt-007 passed on the first try:

Plaintext
token_valid   = true
present_valid = true
status        = ready

This was a real GLM-5.2 output validation, not just a passing unit test.

6. Next is the More Interesting basics/6

The original text of basics/6 is very simple:

Plaintext
* Multiple results

A function can return any number of results.

The `swap` function returns two strings.

.play basics/multiple-results.go

However, the first three formal translation attempts failed consecutively.

The first time, in addition to the existing protected tokens, the model wrote one itself:

Plaintext
`swap`

After recovery, this resulted in two swaps.

The second and third times were even stranger.

The model proactively generated:

Plaintext
.play basics/multiple-results.go 7,9

While the original text only had:

Plaintext
.play basics/multiple-results.go

7,9 happens to correspond to the code range of the swap function in the example code.

The model seemed to be “cleverly” trying to optimize the code display range for me.

But for this translation project, this is precisely an unacceptable structural modification.

7. Retry Feedback Must Not Feed Incorrect Answers Back to the Model

Upon further analysis, I found another issue with the previous retry feedback.

For example, the first failure was simply:

Plaintext
inline code count mismatch

But the feedback would include something like:

Plaintext
check the named directive or protected content near the first difference

It was clearly an inline code error, yet the model was prompted to check directives.

Consequently, the model indeed started modifying .play.

And after .play was incorrectly modified, the next feedback would still send the complete:

Plaintext
expected ...
actual ...

Back to the model.

This could turn into:

The model just generated an incorrect structure, and in the next round, we display that exact incorrect structure back to it.

Therefore, the retry feedback was later changed to generate a safe summary based on the error category.

For example, an inline code error will only tell the model:

The previous output added, deleted, or altered inline code structures on its own. Do not add backtick code in plain text yourself; all already protected inline code must be represented only via existing tokens.

It will no longer mention .play.

Directive errors will also only tell the model:

Do not write present directives such as .play or .image yourself.

The specific error details are still fully saved in:

Plaintext
validation.json

for later debugging, but they will no longer be sent directly back to the LLM.

8. The Most Interesting Question: Where Exactly Did GLM Know swap From?

Then something very surprising happened.

At the time, inline code was using a “full masking” approach.

That is:

Plaintext
`swap`

Before being sent to the model, it would become:

Plaintext
⟪GTI18N_..._000001⟫

What the model actually saw was:

Plaintext
The ⟪GTI18N_..._000001⟫ function returns two strings.

Theoretically, it had no way of knowing what was inside this token.

Yet GLM-5.2’s output accurately wrote:

Plaintext
`swap` ⟪GTI18N_..._000001⟫ 函数返回两个字符串。

At first, I even suspected that the program had leaked swap somewhere else in the request.

So I specifically checked the complete API request:

Plaintext
swap                       0 times
multiple-results.go        0 times
basics/multiple-results.go 0 times

The token-to-original-text mapping was only saved in the local recovery data and was not sent to the model.

In other words, it can be confirmed that:

GLM-5.2 did not directly see swap in this API request.

As for why it was able to exactly fill in swap, there is no further way to prove whether it was:

  • Inferred from “The ___ function returns two strings.” and the Go tutorial context;
  • Having seen the original A Tour of Go text in its training data;
  • Or a combination of both.

But at least one thing is certain:

Masking the semantic content does not mean the LLM truly does not know what should be there.

9. Perhaps We Underestimated the LLM’s “Cleverness”

This made me rethink the protection strategy.

The original idea was:

If swap cannot be translated, then simply do not let the model see it.

Thus:

Plaintext
`swap`

was entirely turned into an opaque token.

But for current LLMs, seeing:

Plaintext
The <token> function returns two strings.

It might very well think:

“There is clearly a function name missing here, and I know what it should be.”

So it proactively fills swap back in.

And the token must be retained.

Ultimately, this results in:

Plaintext
`swap` <token>

In other words:

By masking the semantics to prevent the model from making arbitrary changes, we instead created a semantic void that the model is very eager to proactively fill.

10. Shifting from “Hiding Content” to “Only Protecting Structure”

Therefore, the inline code protection scheme was also adjusted.

Instead of:

Plaintext
The &lt;a completely opaque token> function returns two strings.

It became:

Plaintext
The &lt;inline code start marker>swap&lt;inline code end marker> function returns two strings.

This way:

  • swap remains visible to the model;
  • The model can fully understand the sentence;
  • The backtick structure is protected by the program;
  • The content between the opening and closing markers must match the source text verbatim;
  • Actions like swap2, exchange, translating into Chinese, or modifying whitespace will be directly rejected.

This forms a very unified approach with the aforementioned emphasis structure protection.

Emphasis structure:

Plaintext
&lt;italic start>after&lt;italic end>

The after in the middle:

Can be translated.

Inline code:

Plaintext
&lt;code start>swap&lt;code end>

The swap in the middle:

Allowed to be seen by the model, but not allowed to be modified.

11. The First Real Validation Still Failed

After modifying the inline code protection, I reran basics/6.

It still failed:

Plaintext
inline code sentinel 1 content changed

After checking GLM-5.2’s raw output, I found it generated:

Plaintext
`swap` &lt;inline code start marker>&lt;inline code end marker> 函数返回两个字符串。

In other words, it did not change swap into something else.

What it did was:

Plaintext
Original input:

&lt;start>swap&lt;end>

Model output:

`swap` &lt;start>&lt;end>

It moved swap out from between the two markers, and then added backticks itself.

This time, the program’s new strict check worked.

Because what was originally between the opening and closing markers should have been:

Plaintext
swap

Now it had become an empty string, so it was rejected directly before candidate generation.

12. The Protection Protocol Changed, So the Prompts Must Change Too

After continuing to check the complete request, I realized:

Although the program had already switched to paired protection markers, the prompt still only told GLM:

Each token must appear exactly once as is.

It even stated:

Tokens can be repositioned to accommodate natural Chinese word order.

But it did not tell the model:

  • Which two tokens form a pair;
  • swap must always remain between the two tokens;
  • swap is not allowed to be translated or moved;
  • It must not add backticks itself;
  • Backticks will be restored by the program.

So from the model’s perspective, it did not truly violate the rules as it understood them.

It retained both tokens.

It also retained swap.

It just reorganized the three into what it considered a more reasonable form.

Therefore, a dynamically generated structural protocol was subsequently added.

For inline code, the prompt now explicitly states:

Plaintext
These are the opening token and closing token of the same inline code structure.

The currently visible code content between them must be preserved verbatim within the same pair.

It must not be translated, rewritten, added to, deleted, moved outside the pair, or have other content moved in.

Do not add backticks yourself.

Backticks are restored by the program.

For emphasis structures, the model is explicitly told:

The natural language between the opening and closing markers can be translated, but the translated content must always remain inside the original structure.

This way, the model finally knows:

Plaintext
Inside inline code:
Visible, but cannot be modified

Inside emphasis structures:
Visible, and can be translated

13. basics/6 Finally Passed

After updating the prompt protocol, I executed again:

Bash
go run -mod=readonly ./cmd/tour-i18n translate run \
    -dev \
    --locale zh-CN \
    --id basics/6

This time:

Plaintext
attempts: 6
status: ready

token_valid: true
present_valid: true
failures: []
passed: true

The final translation is:

Plaintext
* 多返回值

函数可以返回任意数量的结果。

`swap` 函数返回两个字符串。

.play basics/multiple-results.go

The structure is correct, and the Chinese phrasing is very natural.

Figure 1: After adjusting inline code protection and the paired structure protocol, basics/6 finally passes validation and displays the Chinese page normally
Figure 1: After adjusting inline code protection and the paired structure protocol, basics/6 finally passes validation and displays the Chinese page normally

As can also be seen from this actually rendered page, swap in the Chinese text on the left is correctly displayed as inline code, while the right side still uses the official original multiple-results.go example code.

This is exactly the effect this round of adjustments aimed to achieve:

The Chinese text can be translated naturally, the technical content remains as is, and the page structure is still strictly controlled by the program.

14. Ultimately, All 10 Ordinary Pages Are ready

At this point, the two blocked pages among the initial 10 ordinary pages have both been resolved.

The final result became:

Plaintext
basics/4   ready
basics/5   ready
basics/6   ready
basics/7   ready
basics/8   ready
basics/9   ready
basics/10  ready
basics/11  ready
basics/12  ready
basics/13  ready

That is:

Plaintext
ready   = 10
blocked = 0
pending = 0

To more intuitively confirm the final status of this batch of pages, I separately organized the pages, statuses, and attempt counts from status.tsv:

Figure 2: The first batch of 10 ordinary pages all enter ready status after the test run and process calibration
Figure 2: The first batch of 10 ordinary pages all enter ready after the test run and process calibration

The characteristics of this round are also easy to see from the attempt counts.

basics/4 ultimately recorded 7 attempts, and basics/6 recorded 6. This does not mean that ordinary pages generally require this many translation attempts, but rather that these two pages bore the brunt of the process calibration tasks during the development phase.

In contrast:

Plaintext
basics/5   1
basics/7   1
basics/8   1
basics/9   1
basics/10  1
basics/11  1
basics/13  1

all only took one attempt.

basics/12 also only took two.

In other words, the actual pass rate for ordinary pages is already quite good.

15. Reviewing the Chinese Quality Once More Before Committing

Before the formal commit, I had ChatGPT quickly review the Chinese text of these 10 pages.

The result found no technical errors that had to be corrected; it only made minor Chinese polishing to 5 pages.

For example:

Plaintext
接受了两个

was adjusted to:

Plaintext
接受两个

And:

Plaintext
var 声明可以包含初始化器,每个变量一个。

was adjusted to:

Plaintext
var 声明可以为每个变量指定一个初始化器。

As well as:

Plaintext
变量声明可以像导入语句一样被“打包”成块

was adjusted to:

Plaintext
变量声明可以像导入语句一样分组写成块

These all belong to final tweaks for Chinese naturalness and do not affect the structure or technical meaning.

After the modifications, the 10 pages were rerun through the unified candidate validation:

Plaintext
candidate OK: locale=zh-CN page_id=basics/4
candidate OK: locale=zh-CN page_id=basics/5
candidate OK: locale=zh-CN page_id=basics/6
candidate OK: locale=zh-CN page_id=basics/7
candidate OK: locale=zh-CN page_id=basics/8
candidate OK: locale=zh-CN page_id=basics/9
candidate OK: locale=zh-CN page_id=basics/10
candidate OK: locale=zh-CN page_id=basics/11
candidate OK: locale=zh-CN page_id=basics/12
candidate OK: locale=zh-CN page_id=basics/13

All passed.

However, this quick manual review was still just a quality observation during the development calibration phase.

The formal goal of the project has not changed:

Page-by-page manual proofreading will not be set as a mandatory fixed process before all pages are published.

If subsequent ordinary pages continue to perform stably, we should gradually shift to focusing on inspecting abnormal pages and sampling ordinary pages.

16. This Time Formed Two Git Commits

To avoid mixing translation engine modifications with translation outputs, this was split into two commits.

The first part is the translation process and protection mechanism:

Plaintext
6a55d0c feat: 完善翻译结构保护与失败恢复流程

The second part is the translation results and complete audit of the 10 ordinary pages:

Plaintext
801db69 feat: 完成首批 10 个普通页面翻译

Ultimately, they have been pushed to:

Plaintext
origin/main

After the push was completed, the local workspace also returned to a clean state.

17. The Biggest Gain This Time Is Not “Translating 10 More Pages”

If you just look at the numbers, this round merely completed 10 more pages.

But I feel that what is truly important is not the page count, but having gained a deeper understanding of the “LLM translation + deterministic structure protection” approach.

At the very beginning, my protection strategy was closer to:

If the model cannot change it, hide it all.

This time, it gradually shifted to:

Try to let the model see the content needed to understand the semantics, and only entrust truly dangerous structural boundaries to program protection.

This can now be preliminarily summarized into a few scenarios.

Ordinary Natural Language

Directly handed over to the model for translation.

Emphasized Text

For example:

Plaintext
_after_

Protect the opening and closing structure, but allow the internal content to be translated.

Inline Code

For example:

Plaintext
`swap`

Protect the opening and closing structure, let the model continue to see the internal content, but strictly prohibit modifications.

Untranslatable Structures Like .play and Link Targets

This kind of content does not need the model to understand or translate it; it can still be entirely hidden and then deterministically restored by the program.

This is more nuanced than simply saying “tokenize everything.”

18. The Stronger the LLM, the Less It Can Be Treated as an Ordinary String Replacer

The swap section left a particularly deep impression on me.

The program had already confirmed:

Plaintext
In the API request:
swap = 0 times

But the model still accurately filled in swap.

This makes me feel that when using increasingly capable LLMs, we cannot only consider:

Will it make basic mistakes?

We must also consider:

Will it over-interpret, and then cleverly do things for you that were never requested at all?

It might:

  • Fill back in hidden content based on context;
  • Proactively optimize the display range of .play;
  • Automatically add backticks to code;
  • Attempt to repair structures it considers “incomplete” into a more reasonable form.

For ordinary chat, these capabilities might be very helpful.

But for a translation pipeline that demands strict structural fidelity, this “cleverness” can instead become a new source of uncertainty.

Therefore, the program cannot try to make the model “dumber.”

A more appropriate approach might be:

Explain the structural protocol clearly, while using a deterministic program to limit the scope of what the model can actually modify.

19. Next Phase: Reducing the Frequency of Development Intervention

Although only 10 ordinary pages were translated this round, the development cost was actually not low.

Because we are still in the process calibration phase:

Plaintext
Discover failure
→ Analyze request / response
→ Modify protection logic
→ Write tests
→ Real regression
→ Analyze again

This pattern cannot continue all the way until all pages are completed.

Otherwise, whether it is time, GLM API Tokens, or Codex usage quotas, they will all be consumed very quickly.

Especially now that the project has entered a rather critical phase:

The previous representative pages and the first batch of ordinary pages were essentially helping me stabilize the translation tool itself.

The subsequent goal should gradually become:

Plaintext
Batch translate a set of ordinary pages
→ Automatic validation
→ Most directly become ready
→ Only abnormal pages enter in-depth analysis

Rather than modifying the translation framework every time a page is translated.

So what really needs to be observed next is:

After the emphasis structures, inline code, retry feedback, and network recovery mechanisms have all been perfected this time, whether the next batch of ordinary pages can still maintain a high pass rate.

If the majority of pages in subsequent consecutive batches can enter ready with a single attempt or minimal retries, without frequently exposing new common structural issues, we should gradually stop the development approach of “modifying the system every time a special output is encountered” and officially enter the batch translation phase.

After all, the ultimate goal of this project is not to build an infinitely complex translation framework.

Rather, it is to establish a set of:

Simple enough, strict enough engineering workflow that can stably complete the multilingual translation of A Tour of Go and continuously sync with upstream.

This round of 10 ordinary pages at least makes me feel one step closer to that goal.

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

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

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

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

关于我  ·  GitHub  ·  邮件联系