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

WordPress Full-Article AI Translation Pitfalls with an Extremely Long Gutenberg Post: From 1000+ Protected Tokens to a Successful Complete Translation

图 1:完整文章首次整篇翻译失败,SlyTranslate 返回受保护标记校验错误

Recently, while continuing to improve my WordPress workflow for automatically translating Chinese articles into English, I encountered an article that was almost ideal as a stress test.

This was not an ordinary article of just a few thousand words, but a technically complex post with a very complicated structure:

  • many Gutenberg blocks;
  • a large number of ordinary paragraphs;
  • 48 quote blocks;
  • many lists;
  • images;
  • 90 Code Block Pro blocks;
  • including Plaintext code blocks whose content needed to be translated;
  • and more than 300,000 characters of body content.

My goal, however, had not changed:

Do not split the article and do not call the model paragraph by paragraph. Continue to let GLM-5.2 translate the entire article in a single request, while using automatic validation to ensure that the Gutenberg structure is not damaged.

As a result, this article exposed several deeply hidden problems in the existing translation pipeline.

More interestingly, what ultimately needed to change was not the model itself, but my definition of what counts as structure and what should be allowed to change naturally during translation.

1. The Initial Problem: The Model Had to Mechanically Copy Too Many Structural Tokens

To prevent AI translation from damaging Gutenberg blocks, I had previously added protected tokens for a large amount of non-translatable structure.

For example:

Plaintext
SWQSTRUCT000001END
SWQSTRUCT000002END
SWQINLINE000001END
……

While translating the body, the model only needed to preserve these tokens exactly as they were.

After translation, the program would restore those tokens to the original Gutenberg comments, HTML, paths, and other structural content.

The design looked perfectly reasonable.

But as the articles became more complex, problems gradually began to appear:

The model not only had to translate the article, but also had to reproduce more than a thousand machine tokens with no semantic meaning at all.

The first time I translated this entire article, it encountered a typical protected-token validation failure.

Figure 1: The first full-article translation failed, and SlyTranslate reported a protected-token validation error
Figure 1: The first full-article translation failed, and SlyTranslate reported a protected-token validation error

The model had not simply “translated one sentence incorrectly.”

The real problem was that:

Plaintext
expected_count
actual_count
missing_tokens
fixed_order

inconsistencies began to appear.

And the more protected tokens there are, the more likely this type of problem becomes.

Ordinary Gutenberg paragraphs in particular already produce:

HTML
<!-- wp:paragraph -->
<p>...</p>
<!-- /wp:paragraph -->

If the beginning and end of every ordinary paragraph become separate protected tokens, a long article can generate hundreds of extra tokens from paragraphs alone.

This made me reconsider a basic assumption:

Does the number of ordinary paragraphs really have to remain exactly the same as in the Chinese source?

2. If the Chinese Has Three Paragraphs, Why Must the English Also Have Exactly Three?

The answer is that it does not.

For example, the Chinese source might be written as:

Plaintext
这是第一句话。

这是补充说明。

因此我们得到结论。

After translation into English, the model could naturally organize the same content into two paragraphs.

The reverse is also true.

A very long Chinese paragraph may sometimes read more naturally when split into two English paragraphs.

So what truly needs to be preserved strictly is not this:

The number of ordinary paragraphs must remain unchanged at a 1:1 ratio.

Instead, the real rule should be:

Ordinary paragraphs must not cross genuine structural boundaries such as headings, quotes, lists, images, code, or tables.

Based on this idea, I introduced a new mechanism:

Plaintext
SWQPARARUNSTART......
SWQPARARUNSTOP......

the “paragraph run.”

Within a safe, contiguous run of ordinary paragraphs, the model no longer has to preserve every individual Gutenberg paragraph comment.

What the model sees is simply:

Plaintext
PARAGRAPH RUN START

<p>第一段</p>
<p>第二段</p>
<p>第三段</p>

PARAGRAPH RUN STOP

Inside this region:

  • 3 paragraphs may be translated into 2;
  • 1 paragraph may also become 2;
  • as long as they remain valid top-level <p> elements;
  • and they must not cross structural boundaries such as quotes, headings, lists, images, or code.

After translation, the local program regenerates the Gutenberg paragraph comments.

3. Protected Tokens Dropped from 1000+ to 506

After this change was deployed, I ran another real full-article translation using the same article.

The execution data from the successful run was:

Figure 2: After introducing paragraph runs, the 320,000-character source was reduced to a translation payload of about 42,000 characters, the protected-token count fell to 506, and the entire article returned successfully in a single request
Figure 2: After introducing paragraph runs, the 320,000-character source was reduced to a translation payload of about 42,000 characters, the protected-token count fell to 506, and the entire article returned successfully in a single request

The key data was:

Plaintext
source_chars: 324981
payload_chars: 42137
protected_count: 506
request_count: 1
translation_tail_guard_status: present
translation_tail_guard_count: 1
content_result: string
error_code: None

The most important number was:

Plaintext
protected_count: 506

Under an earlier input structure, this article required the model to preserve more than 1,000 protected tokens.

After paragraph runs were introduced, that number dropped dramatically.

And the entire article still made only:

Plaintext
request_count: 1

In other words, I did not fall back to any of the following just because the article was complex:

  • translating it in sections;
  • making multiple model requests;
  • translating each block independently;
  • manually stitching translated paragraphs together.

I still kept the same principle:

One article, one complete model request.

But the work was not finished yet.

4. The Model Returned the Complete Article, So Why Was It Still Classified as a Gutenberg Structure Change?

After the new paragraph-run mechanism eliminated a large number of structural tokens, the next real test no longer reported:

Plaintext
Protected token validation failed

Instead, it reached the later final structure validation stage:

Plaintext
The Gutenberg block structure changed during full-article translation.

That was actually a good sign.

It meant the execution flow had already progressed to:

Plaintext
Model returned the complete response
→ Tail-integrity check passed
→ Protected-token validation passed
→ Paragraph-run validation passed
→ Plaintext and other content restored
→ Final Gutenberg structure comparison

In other words, the problem had been narrowed down to the very last step.

So I added dedicated Gutenberg structure-drift diagnostics.

Instead of merely telling me:

Plaintext
Structure differs

the diagnostics now recorded:

Plaintext
first_mismatch_index
source_item_at_mismatch
restored_item_at_mismatch
source_signature_context
restored_signature_context

The first genuine difference was found almost immediately.

5. The First “Structure Change” Was Not a Structure Change at All

The diagnostics showed:

Plaintext
first_mismatch_index: 67

At this position, both the source article and the restored translation contained:

Plaintext
block_name: kevinbatdorf/code-block-pro
language: plaintext

There had been no block-type change whatsoever.

What differed was the content.

Figure 3: Final structure validation located the mismatch in Code Block Pro—the block structure had not changed at all; only the Plaintext content had been correctly translated from Chinese into English, but hashing the complete attributes incorrectly classified it as structure drift
Figure 3: Final structure validation located the mismatch in Code Block Pro—the block structure had not changed at all; only the Plaintext content had been correctly translated from Chinese into English, but hashing the complete attributes incorrectly classified it as structure drift

Source content:

Plaintext
正文 A

.image /tour/static/img/tree.png

正文 B

After translation:

Plaintext
Body text A

.image /tour/static/img/tree.png

Body text B

This was clearly exactly what I wanted to see.

The key detail was:

Plaintext
language: plaintext

This was a Plaintext Code Block Pro block.

Plaintext is supposed to be translatable.

The problem was in the final structure signature.

At the time, the structure signature computed a SHA-256 hash over the complete attributes object.

But Code Block Pro attributes contain not only:

Plaintext
language
theme
lineNumbers
fontSize
copyButton

these genuine configuration fields, but also:

Plaintext
code
codeHTML
highestLineNumber

Among them:

  • code is the translated text;
  • codeHTML is regenerated from the translation;
  • highestLineNumber may also be recalculated when the number of translated lines changes.

This created a very typical logic conflict:

Plaintext
Plaintext restoration logic:
These fields are allowed—and expected—to change

Final structure validation:
These field changes = Gutenberg structure change

So the model had actually done the right thing.

It was the validator that had produced a false positive.

6. Structure Validation Cannot Simply Ask Whether an Attribute Changed

I ultimately refined the structure signature for Plaintext Code Block Pro blocks.

Only when the block is:

Plaintext
kevinbatdorf/code-block-pro

and its language belongs to:

Plaintext
plaintext
plain
text
txt

does the final structure signature ignore the three content fields that are explicitly allowed to change:

Plaintext
code
codeHTML
highestLineNumber

All other configuration is still compared strictly.

For example:

Plaintext
language
theme
bgColor
textColor
fontSize
fontFamily
lineNumbers
copyButton
useTabs

If any of these genuine configuration values changes, the result is still treated as a structural error.

For Code Block Pro blocks that are not Plaintext:

the complete attributes object is still compared strictly.

So this change was not:

“Just loosen Code Block Pro validation so this particular article can pass.”

Instead, it redefined a more accurate boundary:

Content fields and structural configuration fields are not the same thing.

7. The Other Three “Missing Structures” Turned Out to Be Nothing but Whitespace

The diagnostics contained another interesting result:

Plaintext
source_signature_count: 588
restored_signature_count: 585

In other words, in addition to the Code Block Pro attributes-hash mismatch, the translation appeared to be missing three structure-signature items.

Further comparison showed that none of the following were missing:

There were no missing:

  • quotes;
  • headings;
  • lists;
  • images;
  • Code Block Pro;
  • separators.

Every missing item was:

Plaintext
PARAGRAPH_RUN

Tracing the problem further showed that it came from a type of unnamed item returned by WordPress parse_blocks().

Some Gutenberg blocks are separated only by line breaks and spaces:

Plaintext
paragraph
whitespace
paragraph

That whitespace may be parsed as:

Plaintext
blockName = null

The old logic did not add this unnamed block to the structure signature, but it still reset:

Plaintext
in_paragraph_run

to its default state.

As a result, the source could effectively become:

Plaintext
PARAGRAPH_RUN
whitespace
PARAGRAPH_RUN

while the final signature looked like only:

Plaintext
PARAGRAPH_RUN
PARAGRAPH_RUN

After translation, if the whitespace formatting changed:

Plaintext
PARAGRAPH_RUN

the validator then incorrectly concluded that:

one paragraph run had disappeared.

In reality, no Gutenberg structure had been lost at all.

8. Whitespace Can Be Ignored, but Real Freeform Content Cannot

Here, too, the solution could not simply be:

Ignore every blockName=null item.

Some unnamed blocks may contain meaningful legacy HTML or free text.

So the final rule became:

Pure-whitespace freeform content

It must satisfy:

Plaintext
blockName = null
no innerBlocks
content contains only whitespace characters

This kind of content:

does not enter the structure signature and does not break a paragraph run.

Meaningful freeform HTML / text

For example:

HTML
<div class="legacy">
    Visible freeform HTML
</div>

This kind of content is not silently ignored.

Instead, it produces an independent:

Plaintext
FREEFORM:<SHA-256>

structure signature.

In other words:

Meaningless formatting whitespace should not affect structural decisions, but genuine freeform content must still be protected strictly.

This was one of the parts of the change that I was particularly satisfied with.

The goal was not to keep “loosening” validation until this particular article passed.

It was to distinguish between:

Plaintext
What is genuine structure
What is merely content
What is merely whitespace presentation

9. Every Change Needs Automated Regression Coverage, Not Just Validation Against This One Article

The final fix was committed as:

Plaintext
4089fda fix: 修复 Gutenberg 结构签名误判

Before that, I had also added a diagnostic commit specifically to locate the problem:

Plaintext
afdc88e feat: 增强 Gutenberg 结构漂移诊断
Figure 4: After fixing the Gutenberg structure-signature false positives, the final commit reached the main branch and all key regression tests for paragraph runs, Plaintext, protected tokens, and related behavior passed
Figure 4: After fixing the Gutenberg structure-signature false positives, the final commit reached the main branch and all key regression tests for paragraph runs, Plaintext, protected tokens, and related behavior passed

The tests added or retained in this round included:

Plaintext
swq-paragraph-run-test.php
swq-plaintext-structure-test.php
swq-token-validation-test.php
swq-adjacent-token-repair-test.php
swq-tail-struct-token-repair-test.php

In addition to the real production case, the tests specifically verify that:

  • changes to Plaintext Code Block Pro code are accepted;
  • changes to codeHTML are accepted;
  • changes to highestLineNumber are accepted;
  • theme changes still fail;
  • language changes still fail;
  • lineNumbers changes still fail;
  • attribute changes in non-Plaintext Code Block Pro blocks still fail;
  • pure-whitespace freeform content does not break paragraph runs;
  • meaningful freeform content enters strict hash validation;
  • separators remain strict boundaries;
  • quotes remain strict boundaries.

This matters more than simply getting the current article to translate successfully.

Because the real problem was not:

How can article 25425 be given a special exception?

The real question was:

How can the general rules exposed by this failure be corrected in the translation pipeline?

10. Final Result: The Complete Original Article, Without Simplification, Translated Successfully

After completing these changes, I did not continue deleting quote blocks, nor did I simplify the article into a special version just for testing.

Instead, I went back to:

the original, complete Chinese article with every quote block preserved.

Then I ran another full-article translation.

The result:

Figure 6: The same complete article finally created its English translation successfully
Figure 6: The same complete article finally created its English translation successfully

The WordPress admin finally returned:

Plaintext
Translation created successfully.

One especially important aspect of this success was that:

I did not improve the success rate by:

  • deleting 48 quote blocks;
  • rewriting the article structure in bulk;
  • splitting the translation into dozens of AI requests;
  • translating each Gutenberg block independently;
  • manually stitching together the English body.

I still preserved:

Plaintext
One article
→ One complete GLM-5.2 request
→ Automatic restoration
→ Automatic structure validation
→ Write the English article

11. The Gutenberg Editor Could Open the Translation Normally as Well

A successful response from the translation API was not enough.

The final WordPress content still had to be parsed correctly by Gutenberg itself.

So I opened the generated English article in the editor.

Figure 5: The final English article opens normally in the Gutenberg editor, with paragraph and quote structures correctly recognized
Figure 5: The final English article opens normally in the Gutenberg editor, with paragraph and quote structures correctly recognized

The block navigation panel on the left still showed a large number of:

Plaintext
Paragraph
Quote
Paragraph
Quote
……

There was no:

Plaintext
Attempt recovery

Nor was there any:

Plaintext
The block contains unexpected or invalid content

That meant this was not merely a case where the backend program believed the structure was valid.

The WordPress Gutenberg editor itself could also recognize the final content correctly.

There was one isolated:

Plaintext
.

at the end of the English article. This happened because the model merged the body semantics into the preceding paragraph while leaving behind the period from the end of the original sentence.

From a translation-quality perspective, this was a minor formatting imperfection.

But for now I do not plan to add another automatic rule just for this case.

Because:

An isolated period and damaged Gutenberg structure are problems of completely different severity.

If I added a rule such as “automatically delete single-character paragraphs” merely to remove this . automatically, it could instead damage genuinely valid special content.

If necessary, it can simply be removed manually.

12. What Really Changed Was My Understanding of “Structure Protection”

The biggest lesson from this troubleshooting process was not that I fixed a few more regular expressions or added a few more tests.

It was a clearer understanding of one principle:

Protecting more structure does not automatically make the system safer.

If everything is treated as immutable:

Plaintext
The number of ordinary paragraphs cannot change
No attributes of code blocks may change
Even parse_blocks differences caused by whitespace are not allowed

the result is that:

the model can produce a completely reasonable translation and still be rejected repeatedly by the automated system.

A sound automatic translation pipeline should distinguish among:

Structure that must remain strict

For example:

  • headings;
  • quotes;
  • lists;
  • images;
  • separators;
  • tables;
  • containers;
  • high-risk custom blocks;
  • non-Plaintext code structure;
  • genuinely meaningful HTML / freeform content.

Translation content that may change naturally

For example:

  • the number of consecutive ordinary paragraphs;
  • the text inside Plaintext Code Block Pro;
  • the codeHTML deterministically generated from the text;
  • the highestLineNumber determined by the translated line count.

Presentation differences that should not affect structural decisions

For example:

  • pure whitespace between Gutenberg blocks;
  • freeform whitespace with no actual page semantics.

Only by separating these three categories can automatic translation achieve both goals at the same time:

allow natural expression in the translation without sacrificing Gutenberg content safety.

13. From “The Model Must Copy Structure” to “The Program Owns Structure”

The paragraph-run redesign further confirmed the direction I want to take.

Many of the earlier protection mechanisms were effectively asking the model:

Translate the language while also maintaining Gutenberg on behalf of the program.

But what the model is actually good at is language.

It should not be responsible for mechanically copying:

Plaintext
1000+

semantically meaningless structural tokens.

A more reasonable direction is:

Plaintext
Program identifies structure
→ Send only content that truly needs language-model processing to the model
→ Model handles translation
→ Program restores deterministic structure
→ Program performs final validation

This time, reducing the number of protected tokens to:

Plaintext
506

was not simply about saving Tokens.

More importantly, it meant:

reducing the amount of mechanical structural work assigned to the model.

Let the model handle language, and let the program handle structure.

That is the basic direction I intend to keep following as I continue improving the full-article WordPress AI translation pipeline.

14. Conclusion

At the beginning, this article made me wonder:

Is Gutenberg structure simply too complex for full-article AI translation to be practical?

After this round of troubleshooting, however, the conclusion became even clearer:

The problem is not that “full-article translation is impossible.” The protection and validation mechanisms simply need to understand which changes are legitimate parts of translation.

In the end, this extremely long article—with a large number of paragraphs, quotes, lists, images, and 90 Code Block Pro blocks—was still translated through:

Plaintext
One complete GLM-5.2 request

to complete the entire Chinese-to-English translation.

And the final result opened normally in the Gutenberg editor.

That is far more valuable than simply making one particular article “translate successfully.”

After these fixes, the translation pipeline now has a clearer boundary between ordinary paragraphs, Plaintext Code Block Pro, whitespace freeform content, and Gutenberg structure.

In the next stage, I will continue validating these rules against real historical articles.

The goal remains unchanged:

Send as much of each complete article as possible to the translation model in a single request, while leaving structure restoration, safety validation, and failure decisions to deterministic local code.

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

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

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

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

关于我  ·  GitHub  ·  邮件联系