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

From 103/103 Ready to Full Site Acceptance: A Tour of Go Chinese Edition Adds Official Projections and Localizes Course Metadata

Figure 2: Complete zh-CN formal projection successfully generated. 103 course pages are reassembled into 7 .article files.

作者:

在

The Simplified Chinese course content for the A Tour of Go multilingual translation project has finally reached a very clear stage:

Plaintext
ready=103
pending=0
blocked=0

All 103 official course pages now have a canonical candidate and have passed the automated checks established earlier, including present parsing, structural comparison, and page validation.

I originally thought we could proceed directly to the official release.

However, once I actually started a “complete pre-release preview,” I discovered two layers of previously hidden issues:

  1. Although the repository supports single-page candidate previews, it completely lacks the formal projection capability to reassemble the 103 ready pages into a complete Chinese Tour;
  2. Even if the complete projection and 103/103 HTTP validation fully passed, 7 English course titles still remained in the browser. Further investigation revealed that 7 English subtitles at the same level had also not been included in the original translation model.

Ultimately, this round not only filled in the complete language formal projection but also clearly separated the three localization layers: course content, course metadata, and public UI.


1. All 103 pages being ready does not mean it is ready for release

After the previous translation phase was completed, the current zh-CN status is:

Plaintext
ready=103
pending=0
blocked=0

The catalog is also fixed at:

Plaintext
103 published pages
2 conditional source records

The 103 page_id exactly match the frozen catalog, with no missing, extra, or duplicate pages.

These pages cover 7 .article:

Plaintext
welcome.article       5
basics.article       17
flowcontrol.article  14
moretypes.article    27
methods.article      26
generics.article      3
concurrency.article  11

The total is exactly 103 pages.

But at this point, a very practical question arose:

How can we prove that these 103 independent candidates can ultimately be reassembled into a truly functional, complete Chinese A Tour of Go?

The preview command in the repository previously only had a single-page mode:

Bash
go run -mod=readonly ./cmd/tour-i18n preview \
    --locale zh-CN \
    --id methods/17

It copies the official Tour content and then replaces only the Section that the specified page belongs to.

This capability is well-suited for the translation development phase, but it cannot replace the pre-release validation for an official launch.

Because the official release faces:

Once all 103 pages enter the 7 .article simultaneously, is the entire site still correct?


2. While preparing the first complete release preview, a capability gap was immediately discovered

I originally asked Codex to perform a “103-page complete zh-CN official release projection preview.”

Instead of forcing a temporary workaround, it stopped directly after checking the current state of the repository.

The reason was clear:

The repository currently lacks a complete formal projection implementation.

There is no build, and no complete language preview.

The existing BuildCandidatePreview strictly requires a single page_id and is only responsible for replacing one Section.

This actually confirmed one thing for me:

We cannot assume that the final release artifact is definitely correct just because the 103 candidates individually pass validation.

Therefore, what needed to be added first in this round was not publish, but a more fundamental layer beneath it:

Complete language formal projection.


3. Adding BuildLocaleProjection: Generating a complete language site in one pass

This time, a unified BuildLocaleProjection was added.

Its official input is not a development attempt, but rather:

  • catalog;
  • locale status;
  • canonical ready candidate;
  • upstream Tour content.

During the build, it strictly requires:

  • all official pages to be ready;
  • each page to have a canonical candidate;
  • the candidate file to actually exist;
  • the page_id set to exactly match the catalog;
  • no pending allowed;
  • no blocked allowed;
  • no missing pages allowed;
  • no extra pages allowed;
  • no silently falling back to upstream English content.

The 103 pages are first aggregated by .article and then replaced all at once.

This avoids the issue where multiple Section replacements within the same article cause a later write to overwrite the previous result.

At the same time, the original single-page preview and the new complete projection reuse the same set of:

  • Section locating;
  • candidate loading;
  • welcome special projection;
  • present parsing;
  • structural validation.

A new set of assembly logic was not duplicated just for the official release.


4. Both complete build and complete preview are now available

The repository now supports complete language builds:

Bash
go run -mod=readonly ./cmd/tour-i18n build \
    --locale zh-CN

It also supports complete language previews:

Bash
go run -mod=readonly ./cmd/tour-i18n preview \
    --locale zh-CN

The original single-page mode is retained:

Bash
go run -mod=readonly ./cmd/tour-i18n preview \
    --locale zh-CN \
    --id methods/17

This means the two use cases are now separated:

  • With --id: single-page candidate preview during translation development;
  • Without --id: complete language preview composed of all canonical ready candidates.

The actual build result is:

Plaintext
locale=zh-CN
ready=103
pending=0
blocked=0
pages=103
articles=7
Figure 1: Complete A Tour of Go Simplified Chinese preview site. Course pages, course metadata, and public UI are all fully localized.
Figure 1: Complete A Tour of Go Simplified Chinese preview site. Course pages, course metadata, and public UI are all fully localized.

The biggest difference between this complete preview and the previous single-page preview is:

The browser now sees a site composed of 103 canonical ready candidates together, rather than just the current page being replaced.


5. The 103 pages are reassembled into 7 .article

After the complete build, the final result is:

Plaintext
ready=103
pending=0
blocked=0
pages=103
articles=7

The generated content is located in an independent temporary projection directory and does not modify candidates, status, or official repository content.

Figure 2: Complete zh-CN formal projection successfully generated. 103 course pages are reassembled into 7 .article files.
Figure 2: Complete zh-CN formal projection successfully generated. 103 course pages are reassembled into 7 .article

After the build is complete, the final .article is re-parsed using present.

This step is crucial.

Previously, the question was:

Is the candidate itself valid?

Now it goes a step further:

After the candidate is reassembled back into the final article, is the entire document still valid?

This includes some special structures that were previously handled, which all re-enter the final projection:

  • Remote server branch for welcome/1;
  • #appengine: conditional Section for welcome/4 and welcome/5;
  • .play;
  • directive;
  • inline code;
  • links;
  • static preformatted code;
  • emphasis / font span;
  • Section topology.

In the final welcome.article, the #appengine: prefix that should have been removed is also no longer present.


6. You can’t just validate the build; you must actually visit all 103 pages

After the complete projection was successfully generated, I performed another full HTTP page-level validation.

Instead of sampling a few representative pages, I read directly from:

Plaintext
data/tour-pages.tsv

to read all official page_id and request them one by one:

Plaintext
http://127.0.0.1:3999/tour/<page_id>

The final result:

Plaintext
total=103
passed=103
failed=0

A few other previously special or representative pages were also checked individually again:

Plaintext
welcome/1     PASS
welcome/4     PASS
welcome/5     PASS
moretypes/18  PASS
methods/17    PASS
Figure 3: All 103 course pages of the complete zh-CN projection passed HTTP page-level validation, with 103 successes and 0 failures.
Figure 3: All 103 course pages of the complete zh-CN projection passed HTTP page-level validation, with 103 successes and 0 failures.

The public UI is also normal:

HTML
<html lang="zh-CN">

The browser title is:

Plaintext
Go 语言之旅

The public UI also shows:

Plaintext
切换主题

Representative static resources such as CSS, JavaScript, and images all returned HTTP 200.

Up to this point, I had thought:

103/103 could serve as the final complete preview validation result.

As a result, while preparing blog screenshots in the next step, I discovered another issue that was completely uncovered by the previous automated validation.


7. Discovered while preparing screenshots: why is there still English in the navigation?

I opened:

Plaintext
http://127.0.0.1:3999/tour/methods/17

to take a screenshot of the complete Chinese version in the browser.

But after a glance at the right-side navigation, I realized something was very wrong.

The page content was already in Chinese, the public UI was in Chinese, and many Section titles had already been translated.

However, the course navigation still showed:

Plaintext
Welcome!
Packages, variables, and functions.
Flow control statements: for, if, else, switch and defer
More types: structs, slices, and maps.
Methods and interfaces
Generics
Concurrency
Figure 4: During the first complete preview, the course navigation still retained 7 upstream English titles.
Figure 4: During the first complete preview, the course navigation still retained 7 upstream English titles.

At first, I thought only a few titles under “basics” had been missed.

After scrolling down further, I realized:

Generics and Concurrency were also still in English.

A very obvious pattern emerged at this point:

Exactly 7 entries, and there currently happen to be exactly 7 .article.

This did not look like an accidental omission; it looked more like an entire layer was missed by the translation data model.


8. The root cause is not the Section, but present.Doc.Title

Further inspection confirmed that these 7 text entries are the first lines of the 7 .article, respectively.

For example:

Plaintext
welcome.article
Welcome!
Plaintext
basics.article
Packages, variables, and functions.
Plaintext
methods.article
Methods and interfaces

In the present data structure, these are not present.Section, but rather:

Plaintext
present.Doc.Title

After the Tour service reads the complete .article, it maps them to:

Plaintext
doc.Title
    ↓
lesson.Title

And the 103 existing page_id correspond to:

Plaintext
doc.Sections
    ↓
lesson.Pages[]

In other words:

The 103 candidates only cover the top-level present.Section and never covered the .article root-level metadata.

This perfectly explains why none of the previous processes reported errors:

Plaintext
candidate validate
        ↓
只检查 Section

BuildLocaleProjection
        ↓
只替换 catalog 中的 Section

HTTP 103/103
        ↓
只证明 103 个页面能正常路由、渲染

None of the layers required:

Plaintext
present.Doc.Title

to be already localized.


9. After further investigation, it’s not just 7 Titles

The problem actually goes one layer deeper than what was seen in the screenshot.

Besides:

Plaintext
present.Doc.Title

each .article also has:

Plaintext
present.Doc.Subtitle

In the Tour, this ultimately becomes:

Plaintext
lesson.Description

The current 7 .article also each retain an upstream English Subtitle.

For example, basics:

Plaintext
Learn the basic components of any Go program.

generics:

Plaintext
Go supports generic programming using type parameters.
This lesson shows some examples for employing generics in your code.

Therefore, what was actually missing was not 7 entries, but:

Plaintext
7 个 Doc.Title
+
7 个 Doc.Subtitle
=
14 条根级课程 metadata

This means that fixing only the 7 titles visible in the navigation is not enough.


10. These 14 entries were not forced into the 103 pages

Here, I ultimately did not modify:

Plaintext
ready=103
pending=0
blocked=0

Because this status itself is not wrong.

The 103 represents:

The candidate status of the 103 official present.Section.

If I were to suddenly change the project to “110 pages” just to accommodate 7 .article metadata, it would actually break the original model.

Ultimately, I explicitly split the current multilingual content into three layers:

Plaintext
课程页面
103 / 103 ready

课程元数据
7 / 7 localized
title    7 / 7
subtitle 7 / 7

公共 UI
localized

This way, when adding other languages in the future, the responsibilities of each type of resource will be clearer.


11. Adding an independent article metadata localization resource

Ultimately, the following was added:

Plaintext
locales/zh-CN/article-metadata.json

Each article is independently maintained with:

Plaintext
article
title
subtitle

The current 7 zh-CN course titles are:

  • Welcome!
  • Packages, variables, and functions
  • Flow control statements: for, if, else, switch, and defer
  • More types: structs, slices, and maps
  • Methods and interfaces
  • Generics
  • Concurrency

The corresponding 7 Chinese Subtitles have also been added.

For example:

basics

Learn the basic components of any Go program.

moretypes

Learn how to define new types based on existing ones: this lesson covers structs, arrays, slices, and maps.

generics

Go supports generic programming using type parameters. This lesson demonstrates how to use generics in your code.

concurrency

Go provides concurrency constructs at the language level. This lesson introduces these constructs and how to use them.


12. Metadata also adopts a “missing means failure” strategy

Although the data volume in this layer is small, a strategy of “falling back to English if not found” was not adopted.

The official article set is dynamically derived from the catalog.

The build strictly requires:

Plaintext
正式 article 集合
==
locale metadata article 集合

Any of the following situations will directly cause the complete build to fail:

  • missing article;
  • extra article present;
  • duplicate article;
  • missing title;
  • empty title;
  • missing subtitle;
  • empty subtitle;
  • metadata file does not exist;
  • metadata JSON cannot be parsed.

That is to say:

There is no upstream English fallback.

Otherwise, when adding another language in the future, it would be easy to encounter this again:

Plaintext
103 个页面全部通过
但课程导航悄悄混入英文

This state of being “technically successful, but visually a half-finished product.”


13. Single-page preview also fixed simultaneously

This time, it was not just the complete build that was handled.

The original:

Bash
go run -mod=readonly ./cmd/tour-i18n preview \
    --locale zh-CN \
    --id methods/17

will also apply the article metadata.

This prevents a situation where:

  • the complete preview shows the Chinese lesson title;
  • but the single-page preview still shows the English lesson title.

The complete projection and the single-page preview share the same metadata application entry point.


14. Full validation again after the fix

After the article metadata was fixed, the following was executed again:

Bash
go test ./...

Passed.

catalog:

Plaintext
103 published pages
2 conditional source records

status:

Plaintext
103 pages for zh-CN

complete build:

Plaintext
ready=103
pending=0
blocked=0
pages=103
articles=7

metadata:

Plaintext
article metadata localized=7/7
title localized=7/7
subtitle localized=7/7

After reopening methods/17 in the browser, what was previously seen:

Plaintext
Welcome!
Packages, variables, and functions.
Methods and interfaces
Generics
Concurrency

has respectively become:

Plaintext
欢迎!
包、变量和函数
方法和接口
泛型
并发

At this point, the zh-CN localization across the three layers of course content, course metadata, and public UI has truly closed.


15. The most noteworthy part of this round is not just 103/103

The initial goal of this round was actually very simple:

To do a complete pre-release preview for the 103 pages that were already ready.

But upon actual execution, two “last mile” issues were discovered in succession.

The first was:

There was no complete language formal projection at all.

The second was:

All 103 Sections being correct does not mean that the root-level metadata of the entire .article has also been translated.

The second issue, in particular, was discovered only after:

Plaintext
HTTP total=103
passed=103
failed=0

had already appeared, when I was taking manual browser screenshots.

This also demonstrates once again:

Automated validation should cover the structure as much as possible, but the final actual artifact still warrants a manual visual check.

A manual check does not require re-proofreading the translations of all 103 pages page by page.

But it is well-suited for discovering:

  • navigation layer omissions;
  • metadata layer omissions;
  • overall page layout;
  • public UI;
  • issues that only appear after the actual site is assembled.

16. Two commits in this round

Committed after the complete language formal projection and preview were finished:

Plaintext
eb3d817 feat: 增加完整语言正式投影与预览

Subsequently, the article/lesson metadata was added:

Plaintext
22e0f6a feat: 增加课程元数据多语言本地化

Both commits have been pushed to main, and the final workspace remains clean.


17. The actual current project status

At this stage, the Simplified Chinese can be explicitly divided into three parts:

Plaintext
Section candidate
103 / 103 ready

Article metadata
7 / 7 localized
title    7 / 7
subtitle 7 / 7

Public UI
localized

Complete language projection:

Plaintext
pages=103
articles=7

HTTP page-level validation:

Plaintext
total=103
passed=103
failed=0

So it is no longer just:

“103 pages translated.”

Rather, it has been proven that:

The 103 official pages can be reassembled into a complete zh-CN A Tour of Go through a unified formal projection, and run fully as a real Tour service.

However, there is one last very clear boundary:

Production publish is not yet implemented.

The next phase will no longer deal with translation candidates or complete site assembly, but will truly enter:

  • release artifact structure;
  • persistent release directory;
  • atomic release;
  • failure recovery;
  • upstream / locale release metadata;
  • production environment /socket security boundaries;
  • post-release validation.

I plan to continue this part separately and will not cram it into this post.


Conclusion

When we reached ready=103, I originally felt that the Simplified Chinese translation phase was basically over.

But this complete release preview proved once again:

“All translation units are complete” and “the final product is complete” are actually two different things.

Section candidates, article metadata, and the public UI are essentially three different levels.

Only by building the final actual site can you discover whether any of these layers were never included in the translation model.

Coincidentally, the last obvious issue this time was not found by testing, but was seen by me in the browser while preparing screenshots for the blog.

And precisely because of that glance, the following were ultimately added:

Plaintext
present.Doc.Title
present.Doc.Subtitle

This entire layer of multilingual resources.

Now, the 103 course pages, 7 course metadata entries, and the public UI have all entered the unified zh-CN complete projection.

Next, we can finally truly start considering:

How to safely turn the validated complete projection into an official release artifact.

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

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

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

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

关于我  ·  GitHub  ·  邮件联系