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

WordPress AI Translation Troubleshooting in Practice: Why Did a Valid Inline Code Reordering Block Automatic Tail-Structure Repair?

图 1:index 814 的 INLINE Token 换序及中英文 Gutenberg 对照

Recently, while continuing to use SlyTranslate + GLM-5.2 to translate Chinese WordPress articles into English, I ran into another Protected Token validation failure.

This one was particularly interesting.

At first, the symptom looked very similar to the Gutenberg structure-loss issues I had dealt with before: after the model finished translating, some Tokens used to protect the WordPress block structure disappeared, so the automatic validator refused to write the translation.

Naturally, I initially investigated it as another missing-Token problem.

But after several rounds of changes and retranslations, I gradually realized that the situation was not that simple.

The real problem was not “one more Token is missing.”

Instead:

A completely reasonable adjustment to English word order changed the order of two inline-code Tokens. The main validator allowed this change, but the automatic tail-repair logic still required all Tokens to remain in their original order.

In other words, what really needed to be fixed this time was neither the translation nor the Chinese Gutenberg structure, but a logical inconsistency between two sets of validation rules。


1. What I Saw at First Was a Series of Missing Tokens

When this article was first translated with GLM-5.2 in the WordPress admin, the initial failure report showed six missing Tokens.

After that, I cleaned up several places where the Gutenberg content had clearly been split too aggressively, based on their actual context.

For example:

  • a very short standalone introductory paragraph;
  • a normal paragraph immediately followed by a quote block;
  • a complete sentence split into several Gutenberg content units;
  • a standalone quote block following “Final proof:”;
  • and a final sentence split across multiple paragraphs and quote structures.

After these changes, I translated the article again, and the number of missing Tokens did indeed change:

Plaintext
6
→ 4
→ 4
→ 1

On the surface, it looked as though I was gradually getting closer to success.

But one number never changed throughout the entire process:

Plaintext
first_mismatch_index=814

Meanwhile, the total number of Protected Tokens had changed significantly:

Plaintext
1101
→ 1089
→ 1081
→ 1075

The article structure had been revised several times, and the Token count had changed as well, yet the first ordering discrepancy remained fixed at 814。

At that point, continuing to modify the article based only on the final missing_tokens result was starting to feel like the wrong direction.


2. Instead of Chasing the Last Missing Token, Inspect Index 814 Directly

This reminded me of a previous troubleshooting experience.

In an earlier article, “WordPress AI Translation Token Loss at the Tail: From a Superficial Fix to Finding the Real Structural Misalignment”, I encountered a similar situation.

At the time, the visible symptom was a missing STRUCT Token at the end of the article. But after digging deeper, I discovered that the real problem had occurred much earlier, in the middle of the article:

A complete Plaintext block had moved to accommodate natural word order and crossed a Gutenberg STRUCT Token.

So this time, instead of continuing to analyze the last missing Token:

Plaintext
SWQSTRUCT000942END

I decided to go straight to:

Plaintext
first_mismatch_index=814

and inspect what had actually happened between expected and actual at that position.

The answer immediately became clear.

Figure 1: Reordering of INLINE Tokens at index 814 and a Chinese/English Gutenberg comparison
Figure 1: Reordering of INLINE Tokens at index 814 and a Chinese/English Gutenberg comparison

Codex ultimately located the following discrepancy:

Plaintext
index 814 expected:
SWQINLINE000059END

index 814 actual:
SWQINLINE000060END

These two Tokens respectively protected:

HTML
<code>.play</code>

and:

HTML
<code>exercise-errors.go</code>

The original Chinese content was:

HTML
<!-- wp:list-item -->
<li><code>.play</code> 对应的 <code>exercise-errors.go</code> 正常加载;</li>
<!-- /wp:list-item -->

GLM-5.2 translated it as:

HTML
<!-- wp:list-item -->
<li>The <code>exercise-errors.go</code> corresponding to <code>.play</code> loads normally;</li>
<!-- /wp:list-item -->

This is perfectly natural English.

The Chinese order is:

Plaintext
.play
→ exercise-errors.go

For natural English expression, it becomes:

Plaintext
exercise-errors.go
→ .play

Both inline-code objects are still present:

  • neither was lost;
  • neither was added;
  • neither was duplicated;
  • neither crossed a Gutenberg block boundary;
  • and both remained inside the same list-item.

Therefore:

This was not structural corruption. It was a normal cross-language word-order change.


3. Why Did the Main Validator Accept It While Tail Repair Failed?

Further analysis revealed the actual contradiction.

Not every type of Protected Token is required to preserve its original global order.

Inline objects such as INLINE Tokens are allowed to change order within a safe scope so that different languages can be expressed naturally.

For this reason, the system also maintains a separate fixed Token sequence.

In simple terms:

  • Tokens such as INLINE that may be naturally reordered are excluded from strict fixed-order validation;
  • Tokens such as Gutenberg STRUCT that genuinely determine structural safety must still preserve their order exactly.

This explains why the latest diagnostic output contained two very different results:

Plaintext
first_mismatch_index=814

But:

Plaintext
first_fixed_mismatch_position=996

And the final fixed-sequence counts were:

Plaintext
expected_fixed_count=996
actual_fixed_count=995

With:

Plaintext
expected_fixed_at_mismatch=SWQSTRUCT000942END
actual_fixed_at_mismatch=None

In other words:

The first 995 fixed Tokens were all correct. The only genuinely missing Token was the final SWQSTRUCT000942END。

That is exactly the kind of case Tail Repair is designed to handle.

But it did not perform the repair.

The log showed:

Plaintext
protected_token_tail_repair_reason=
actual_sequence_not_expected_prefix

4. The Real Problem: Tail Repair Was Still Checking the Complete Raw Token Order

After inspecting Tail Repair itself, I found that when it determined whether a trailing STRUCT Token could be safely restored, it still required:

The complete actual raw Token sequence must be a strict prefix of the expected raw sequence.

That created a logical conflict.

Earlier, at index 814:

Plaintext
INLINE59 INLINE60

had become:

Plaintext
INLINE60 INLINE59

Although this was a valid reordering, from the perspective of the raw sequence:

Plaintext
actual != expected prefix

So Tail Repair rejected the repair immediately.

The entire chain of events was therefore:

Plaintext
Legal INLINE Token reordering
        ↓
The raw Token sequence no longer preserves the original prefix
        ↓
The fixed Token sequence is still completely safe
        ↓
Only the final STRUCT Token is actually missing
        ↓
Tail Repair rejects the repair because the raw prefix no longer matches

In other words:

The main validator already considered the INLINE reordering valid, but Tail Repair applied another rule that treated the same reordering as unsafe.

That was the actual bug.


5. The Fix Was Not to Remove Safety Checks, but to Unify the Validation Criteria

Once the root cause was clear, the required change was very small.

Previously, Tail Repair used the complete Token sequence for its check:

PHP
if (
    $actual_tokens !==
    array_slice(
        $expected_tokens,
        0,
        count( $expected_tokens ) - $tail_count
    )
) {
    $result['reason'] = 'actual_sequence_not_expected_prefix';
    return $result;
}

It was changed to reuse the system’s existing:

PHP
is_fixed_order_protected_token()

First, the expected and actual fixed Token sequences are generated separately:

PHP
$expected_fixed_tokens = array_values(
    array_filter(
        $expected_tokens,
        [ self::class, 'is_fixed_order_protected_token' ]
    )
);

$actual_fixed_tokens = array_values(
    array_filter(
        $actual_tokens,
        [ self::class, 'is_fixed_order_protected_token' ]
    )
);

Then Tail Repair checks whether the fixed sequence still forms a safe prefix:

PHP
if (
    $actual_fixed_tokens !==
    array_slice(
        $expected_fixed_tokens,
        0,
        count( $actual_fixed_tokens )
    )
) {
    $result['reason'] = 'actual_fixed_sequence_not_expected_prefix';
    return $result;
}
Figure 2: Code diff changing Tail Repair from a raw Token prefix check to a fixed Token prefix check
Figure 2: Code diff changing Tail Repair from a raw Token prefix check to a fixed Token prefix check

This change is important.

It does not mean:

Removing Token-order validation just to make the translation pass.

Instead:

Tail Repair and the main validator now use the same definition of which Tokens must preserve their order.


6. The Parts That Need to Be Strict Are Still Strict

When modifying Tail Repair, I did not want to broaden the structural safety boundary simply to accommodate one real-world case.

So all existing safety conditions were retained.

Automatic tail repair still requires that:

  • no extra Tokens are present;
  • no duplicate Tokens are present;
  • no non-STRUCT Token is missing;
  • missing Tokens must form a contiguous tail of the expected raw sequence;
  • a missing fixed Token from the middle must be rejected;
  • any fixed Token ordering change must be rejected;
  • after the repair, the result must still pass the complete Protected Token validator again.

The new regression tests cover all of these cases.

For the real-world scenario:

Plaintext
STRUCT_A
INLINE_1
INLINE_2
STRUCT_B
STRUCT_TAIL

had become:

Plaintext
STRUCT_A
INLINE_2
INLINE_1
STRUCT_B

the system is allowed to restore:

Plaintext
STRUCT_TAIL

But in the following cases:

A fixed Token is missing from the middle

Reject.

Fixed Tokens are reordered

Reject.

An INLINE Token is genuinely missing

Reject.

An unknown extra Token appears

Reject.

An INLINE Token is duplicated

Reject.

In other words:

What may change is natural-language word order, not structural integrity.


7. The Complete Local Test Suite Passed

After completing the fix, I ran all tests currently listed as applicable in the project README:

Bash
php swq-plaintext-structure-test.php
php swq-token-validation-test.php
php swq-adjacent-token-repair-test.php
php swq-tail-struct-token-repair-test.php
php patch/token-normalization-tests.php
bash patch/run-featured-image-tests.sh

All of them passed.

The featured-image tests reported:

Plaintext
62 tests, 0 failures

I also ran:

Bash
git diff --check

There was no output.

A read-only review of the actual diff was then performed again, confirming that:

  • the change occurred only in Tail Repair’s prefix check;
  • the safety boundary for fixed Tokens was not relaxed;
  • the real production case was covered by regression tests;
  • and the repaired result still had to pass the complete validator.

The final commit was:

Plaintext
9ed3997
fix: 修复行内标记换序阻断尾部结构修复

8. Keep a Recoverable Backup Before Deploying to Production

After committing and pushing the code, I began a minimal production deployment.

Only the following file was deployed:

Plaintext
swq-glm52-translation-tuning.php

No test files were deployed.

The existing production file was first backed up as:

Plaintext
/data/wwwroot/www.shuijingwanwq.com/wp-content/mu-plugins/swq-glm52-translation-tuning.php.bak.20260814-185042

I then ran a PHP syntax check on the production file:

Plaintext
No syntax errors detected in /data/wwwroot/www.shuijingwanwq.com/wp-content/mu-plugins/swq-glm52-translation-tuning.php

Next, I compared the local and production SHA-256 hashes:

Plaintext
Local:
49864495cae01ce5e80f50ad7f0279f7e75ebe05877fce416ef295e1bdc2e6bd

Production:
49864495cae01ce5e80f50ad7f0279f7e75ebe05877fce416ef295e1bdc2e6bd

They matched exactly.

Figure 3: Production backup, PHP syntax check, and matching local/production SHA-256 hashes
Figure 3: Production backup, PHP syntax check, and matching local/production SHA-256 hashes

The deployment process did not:

  • modify the database;
  • modify any article;
  • modify SlyTranslate;
  • restart Nginx;
  • restart PHP-FPM;
  • call GLM-5.2 during deployment.

I first confirmed that the correct code had reached production before performing the final real translation test.


9. Retranslating the Same Article: Success

After the deployment was complete, I returned to the WordPress admin.

I made no further changes to the Chinese article body.

I simply ran the English translation again on the exact same article that had repeatedly failed before.

This time, SlyTranslate returned:

Plaintext
Translation created successfully.

Target language:

Plaintext
English (en)

Model:

Plaintext
Zhipu AI: glm-5.2
Figure 4: After retranslating in production, SlyTranslate shows “Translation created successfully”
Figure 4: After retranslating in production, SlyTranslate shows “Translation created successfully”

At that point, the issue was finally closed.

It was not resolved by continuing to modify the Chinese article to work around the problem, nor by weakening Protected Token validation. Instead, the inconsistency between Tail Repair and the main validator regarding what constituted a “valid ordering change” was corrected.


10. The Most Important Lesson Was More Than Just a Tail Repair Fix

Looking back at the troubleshooting process, I took a slight detour during the first half.

When I repeatedly saw:

Plaintext
missing_tokens

it was easy to naturally assume:

If a Token is missing, inspect the corresponding Gutenberg structure.

And after several rounds of changes, the sequence:

Plaintext
6 → 4 → 4 → 1

also seemed to suggest that the direction was correct.

But there was an important detail that was easy to overlook:

Every run was a completely new generation by GLM-5.2.

Therefore, the number of missing Tokens across different translation runs does not establish a strict causal relationship.

The truly stable and valuable clue was instead:

Plaintext
first_mismatch_index=814

It remained completely unchanged across multiple runs.

Once I inspected that position directly, the problem quickly shifted from:

“Another STRUCT Token is missing at the end.”

to:

“Two INLINE Tokens swapped positions to produce natural English, but Tail Repair rejects a change that the main validator already permits.”

That completely changed the direction of the investigation.


11. Stricter Validation Is Not Always Better Validation

This issue is actually quite similar to another class of problems I recently encountered in the multilingual translation project for A Tour of Go.

Different languages naturally have different word orders.

If a validator treats:

the surface ordering of the source language

as equivalent to:

structural safety

then a perfectly correct translation may still be rejected.

But the opposite approach is also wrong. Natural-language reordering does not mean structural validation should simply be removed.

What really needs to be distinguished is what may change and what must not change.

What may change

  • natural reordering of inline code within the same safe structure;
  • word-order adjustments required by the target language;
  • local changes in expression that do not affect Gutenberg boundaries.

What must not change

  • loss of Gutenberg STRUCT Tokens;
  • fixed Tokens moving across structural boundaries;
  • duplicated Tokens;
  • newly introduced Tokens;
  • damaged code, link targets, or structural boundaries.

A reliable automatic translation system therefore should not require:

“Everything must remain in exactly the same order as the source text.”

Instead:

Allow language to change naturally while strictly fixing in place the parts that genuinely determine structural safety.


12. Conclusion

At first, this failure looked like nothing more than:

Plaintext
SWQSTRUCT000942END

not being returned.

If I had continued modifying the Chinese article around that final Token, I might simply have encountered one failure after another.

What actually helped the investigation converge was going back to an earlier point:

Plaintext
first_mismatch_index=814

That ultimately revealed:

Plaintext
.play
exercise-errors.go

had merely swapped into a completely reasonable order in English.

Yet internally, the system had reached two different conclusions:

Plaintext
Main validator:
Allow

Tail Repair:
Reject

The core fix was therefore very simple:

Plaintext
raw Token prefix
↓
fixed Token prefix

But behind this very small change lies a broader principle for the entire AI translation pipeline:

Automatic validation should strictly protect structural facts, not the surface word order of any particular language.

After this fix was deployed, the same production article successfully passed GLM-5.2 translation.

And as I continue working with increasingly complex Gutenberg technical articles, I believe this boundary—allowing natural expression without sacrificing structural safety—will be more important than simply adding more and more Token rules.

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

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

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

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

关于我  ·  GitHub  ·  邮件联系