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

The A Tour of Go Multilingual Translation Project Goes Live: Finalizing the Homepage, Public Footer, and Production Release Metadata

Figure 1: Official production homepage of the A Tour of Go multilingual translation project

作者:

在

Previous work completed the translation, structural validation, public UI localization, and production deployment infrastructure for the 103 Simplified Chinese course pages of A Tour of Go.

At this stage, although the project was already “accessible,” it was still missing several parts truly intended for public release:

  • A standalone project homepage;
  • Clear project identity and unofficial disclaimer;
  • Public entry points for GitHub, development records, etc.;
  • A unified public Footer;
  • ICP filing information;
  • More explicit production release metadata;
  • A formal deployment process capable of safe updates, verification, and rollback.

On August 12, 2026, I focused on completing this round of final touches and officially deployed the new version to:

https://go-dev.shuijingwanwq.com

During this work, two quite valuable issues unexpectedly surfaced:

First, CDN caching can cause a complete release to end up in a mixed state of “new HTML paired with old CSS”;

Second, if the “latest release time” is saved directly in the source code, it creates a very subtle release loop.

This article records the complete handling process.


1. Making the Root Path the True Project Homepage

The original go-dev.shuijingwanwq.com was more like a site directly running A Tour of Go.

But as the project gradually stabilized, I started to feel that:

go-dev.shuijingwanwq.com should not forever just be equivalent to /tour/.

Because from the very beginning, this project was not designed to only consider a Simplified Chinese version.

The current first phase indeed only completes zh-CN, but the architecture itself is designed for multilingual expansion. In the future, besides A Tour of Go, community translations of other official Go learning materials may also be organized.

Therefore, it was ultimately decided that:

  • /: The homepage for the entire multilingual translation project;
  • /tour/*: The A Tour of Go course;
  • Current default language: Simplified Chinese;
  • When new languages are added later, the same homepage structure will continue to be reused.

The homepage also explicitly added a project identity statement:

Unofficial community multilingual translation project.

And further clarified:

This project has no affiliation or authorization with the official Go project, nor does it represent their endorsement or sponsorship.

This both prevents users from mistakenly thinking this is the official Chinese version of Go and leaves room for continuing to expand into other languages in the future.

Figure 1: Official production homepage of the A Tour of Go multilingual translation project
Figure 1: Official production homepage of the A Tour of Go multilingual translation project

From the final page, it can be seen that the homepage currently includes:

  • Project introduction;
  • Current translation project;
  • Current language;
  • 103 course pages;
  • Latest release time;
  • Official source code baseline;
  • Upstream commit time;
  • English and Simplified Chinese entry points;
  • GitHub;
  • GitHub Issues;
  • Blog development records;
  • Official upstream;
  • Translation and validation principles;
  • Filing and copyright information.

Among these, the “103 course pages” is not a display number hard-coded manually into the page, but comes from the current release result.

This also means that in the future, if the number of upstream courses changes, as long as the new projection and production bundle are correctly generated, the status information can continue to update alongside the release result.


2. The Project’s Own Logo and Favicon

The homepage also added its own site Logo.

The original Go Logo inside the A Tour of Go course was not modified.

The final distinction is:

  • The project homepage uses its own Logo;
  • The /tour/* course area continues to use the official Go Tour style;
  • The browser favicon uses the project’s own icon.

The Logo files are placed directly into the production bundle:

Plaintext
_content/images/site-logo.png
_content/images/site-logo-32.png

Instead of relying online on my WordPress media site.

This way, the release package itself is complete, and project brand resources will not disappear due to anomalies with an external image domain.


3. Adding a Unified Public Footer to Course Pages

Once the project homepage was in place, another issue immediately became apparent:

The course pages themselves still looked like a completely standalone Tour.

After entering the course, it was difficult for users to know:

  • Which community project this is;
  • Where the project homepage is;
  • Where the GitHub repository is;
  • Where the development records are.

Therefore, a unified Footer was also added in this round:

Plaintext
Unofficial community multilingual translation project · Homepage · GitHub · Development records
© 2026 Yongye | Shu ICP Bei 13001590 Hao-1

However, the implementation process for the Footer was more prone to pitfalls than imagined.


4. Why the Footer Ultimately Did Not Use fixed

Initially, I tried fixing the Footer to the bottom of the browser.

This approach looks visually stable, but it is not ideal for a left-right two-column layout like A Tour of Go.

Because a fixed Footer continuously occupies the vertical space of the course.

This is especially noticeable for the right-side code editor:

Space that originally belonged to the code area would be permanently eaten up by the Footer.

Moreover, if other content needs to be added to the page in the future, this layout will become increasingly difficult to maintain.

Ultimately, I abandoned fixed and sticky, returning to the simplest solution:

The Footer is just normal content in the document flow.

That is to say:

  • When page content does not exceed one screen, the Footer naturally appears after the content;
  • When page content exceeds one screen, you must scroll to the bottom of the page to see the Footer;
  • No JavaScript scroll listeners are used;
  • No Footer height compensation variables are needed;
  • No need to permanently reserve bottom space for the course area.

This is a noticeably simpler approach.


5. Full-Width Footer Exposes Right-Side Editor Overflow

After moving the Footer out of the left-side course content, another issue appeared.

The main body of the course has a left-right two-column layout:

  • Left: Teaching text;
  • Right: Code editor and run results.

When the Footer was placed after the entire two-column body, the right-side editor once continued to extend downward a bit, overlapping the Footer.

I finally traced it to this layout section:

CSS
#explorer + div {
    top: 32px;
    height: 100%;
}

The problem was:

  • The element had already been shifted down via top: 32px;
  • But its height was still kept at 100%.

As a result, the actual bottom naturally had an extra 32px.

The final fix was:

CSS
#explorer + div {
    top: 32px;
    height: calc(100% - 32px);
}

This way, the right-side Editor ends exactly at the bottom of the two-column body.

Figure 2: Final layout of the course page, code editor, and full-width public Footer
Figure 2: Final layout of the course page, code editor, and full-width public Footer

Final manual acceptance confirmed:

  • Left and right two-column layout is normal;
  • The right-side Editor does not overlap the Footer;
  • Internal scrolling within the Editor is normal;
  • Pagination navigation position is normal;
  • The Footer spans the entire Tour page;
  • Filing information is displayed correctly.

6. Officially Generating the New production bundle

After the UI and public information acceptance was completed, the official production release began.

The Git commit used for this release was:

Plaintext
acbf24a feat: Improve site homepage and public project information

When generating the production bundle, the following was explicitly passed in:

Plaintext
published_at=2026-08-12T07:23:34Z

Corresponding to Beijing Time:

Plaintext
2026-08-12 15:23:34

Release results:

Plaintext
locale=zh-CN
ready=103
pending=0
blocked=0
pages=103
articles=7

The production metadata also explicitly records:

Plaintext
execution_transport: http-playground-proxy
execution_provider: go.dev
local_socket_enabled: false

The last item is particularly important:

The production environment does not expose the local /socket code execution interface.

Code execution continues to be handled via the remote Go Playground proxy.


7. Explicitly Standardizing Production Release Permissions Again

During the previous deployment, I had already encountered Linux file permission issues, so this time I did not rely on the permissions preserved by the tar package itself.

After unpacking the new release, permissions were uniformly handled:

  • Release directory: root:root, 755
  • Subdirectories: 755
  • bin/tour: 755
  • Regular files: 644
  • Service running user: go-tour:go-tour

Then, I directly verified using the go-tour user:

  • Binary is executable;
  • release.json is readable;
  • _content file is readable.

Only after confirming there were no permission issues did I proceed with the deployment.


8. Start Independently, Then Switch production

Before the official switch, the new release did not directly occupy the production port.

Instead, it was temporarily run on:

Plaintext
127.0.0.1:4005

Independent verification:

  • /
  • /tour/list
  • /tour/welcome/1
  • Logo
  • favicon

All returned HTTP 200.

Also verified:

Plaintext
/socket

Returned:

Plaintext
404

Confirming that the production build did not enable the local execution interface.

Only then was the atomic switch performed:

Plaintext
/data/go-tour/current

From the old version:

Plaintext
/data/go-tour/releases/20260811-zh-CN-925d59d

Switched to:

Plaintext
/data/go-tour/releases/20260812-zh-CN-acbf24a

And the official go-tour service was restarted.


9. Preparing Automatic Rollback for the Switch Process

This switch also incorporated a simple but very practical safeguard.

Immediately after the switch, it checks:

  • Whether the systemd service is active;
  • Whether / returns HTTP 200.

Only if both conditions are met is the switch considered successful.

Otherwise, the script will automatically:

  1. Restore the old current;
  2. Restart the old version;
  3. Output a failure log.

Ultimately, no rollback was triggered.

The new version started up normally right away.


10. Dual Acceptance: Origin Server and Public Internet

After the official service started, I didn’t just check 127.0.0.1:3999.

I also tested separately:

Nginx Origin Server

Plaintext
/
 /tour/list
 /tour/welcome/1
 /images/site-logo-32.png

All returned HTTP 200.

Public HTTPS

Tested the same paths again:

Plaintext
HTTP 200

The homepage also returned:

Plaintext
A Tour of Go Multilingual Translation Project
Figure 3: Official production release, 103 course pages, and public HTTP acceptance
Figure 3: Official production release, 103 course pages, and public HTTP acceptance

The final status in the screenshot includes:

Plaintext
locale: zh-CN
published_at: 2026-08-12T07:23:34Z
pages: 103
articles: 7
execution_transport: http-playground-proxy
execution_provider: go.dev
local_socket_enabled: False

And:

Plaintext
/                        HTTP 200
/tour/list               HTTP 200
/tour/welcome/1          HTTP 200

11. After a Successful Release, a Page That Looked Like a Code Bug Appeared

Just when I thought the release was complete, opening the homepage in the browser showed an obvious anomaly:

The HTML was the new version, but the page had almost none of the new homepage’s styling.

My first instinct was to suspect:

  • Wrong CSS path;
  • Missing files in the production bundle;
  • The homepage template did not load correctly;
  • Nginx returned incorrect content.

But after directly comparing the origin server CSS and the public CSS, I found:

The app.css obtained by the server accessing the origin:

Plaintext
17171 bytes

What the server fetched via the public EdgeOne was also:

Plaintext
17171 bytes

The SHA256 was exactly the same.

But when my own computer accessed the same URL:

Plaintext
14134 bytes

The SHA256 was completely different.

This directly proved:

Different EdgeOne nodes were returning different versions of the CSS.


12. A Site-Level Release Cannot Just Focus on Refreshing One CSS File

Upon further inspection, I discovered:

Not only was the homepage CSS old, but the new Footer on the course pages was also not showing up initially.

So this was no longer an issue with a single static asset, but rather a multi-asset version inconsistency following a complete site release:

  • HTML was new;
  • CSS might be old;
  • Angular partials might also still be in an old cached state.

Finally, in EdgeOne, for:

Plaintext
go-dev.shuijingwanwq.com

A Hostname-level cache flush was executed, selecting:

Plaintext
Delete directly

Instead of “Mark as expired”.

After the flush, locally re-fetching the CSS:

Plaintext
17171 bytes

The SHA256 exactly matched the origin server.

The homepage immediately returned to normal.

After disabling the cache in Firefox and reloading the Angular partials, the Footer also appeared correctly on the course pages.

This experience added a very clear lesson to the official release process:

Whenever a production release involves frontend assets like HTML, CSS, Angular partials, or Logos, the CDN cache for the corresponding Hostname should be flushed synchronously after the version switch is complete; otherwise, a mix of old and new assets may occur.


13. Another More Subtle Issue: What Exactly Should the “Latest Release” Time in the Source Code Be?

After adding “Latest Release” to the production homepage, another architectural issue was discovered.

The release time for this production bundle was:

Plaintext
2026-08-12T07:23:34Z

This time came from:

Plaintext
publish --published-at

It belongs to this production artifact.

Initially, I considered:

After deployment is complete, writing this time back into site-metadata.json in the source code.

But I soon realized this would create a loop.

Assume:

Plaintext
commit A
↓
Build production bundle
↓
published_at = T1
↓
Deploy
↓
Write T1 back to source code
↓
Produces commit B

Here is the problem:

commit B is not the artifact that was actually built and deployed at T1.

If we then release from commit B:

Plaintext
commit B
↓
Produces T2
↓
Write back again
↓
commit C

This can never form a closed loop.


14. Ultimately Separating Development metadata from Production metadata

I finally decided to completely distinguish the two semantics.

In the source code:

Plaintext
_content/tour/site-metadata.json

Now explicitly represents:

Development metadata

Added to it:

JSON
"development": true

And it no longer saves:

Plaintext
published_at

Therefore:

  • go run ./tour
  • full preview
  • single-page preview

The homepage displays:

Plaintext
Development environment

Instead of faking a production release time.

The production bundle is still generated by:

Plaintext
publish --published-at

To generate the official metadata.

In production:

  • Does not include development;
  • Must include a valid published_at;
  • Within the bundle site-metadata.json;
  • Root directory release.json

Both must use the same release time.

Figure 4: Separation of responsibilities between development metadata and production release metadata
Figure 4: Separation of responsibilities between development metadata and production release metadata

The current source code clearly shows:

JSON
"development": true

And there is no published_at.

The corresponding commit is:

Plaintext
c20cc42 refactor: Separate development and production release metadata

While the previous commit actually deployed to production remains:

Plaintext
acbf24a feat: Improve site homepage and public project information

This state of “GitHub main being one internal refactor commit ahead of production” is perfectly normal.

There is no need to do another deployment with no practical user benefit just to keep HEAD and production exactly identical.


15. Why production metadata Must Belong to the release

After this round, this boundary is very clear:

Source code metadata

Responsible for:

  • Development runs;
  • preview;
  • upstream baseline;
  • Current language;
  • Basic status of pages and articles.

production bundle metadata

Responsible for:

  • Current production artifact;
  • published_at;
  • Production runtime homepage display.

release.json

Responsible for:

Describing the release manifest of the same production artifact.

Therefore, the future release process no longer needs:

Release complete → write production time back to source code.

It only needs:

Plaintext
Source code
→ publish --published-at
→ production bundle
→ Deploy
→ Acceptance

The release truly ends here.


16. Current Final Status

As of this official release:

A Tour of Go Simplified Chinese

Plaintext
ready   = 103
pending = 0
blocked = 0

Total:

Plaintext
103 course pages
7 articles

Official Site

https://go-dev.shuijingwanwq.com

GitHub

https://github.com/shuijingwan/go-tour-i18n

production

Plaintext
/data/go-tour/releases/20260812-zh-CN-acbf24a

Currently:

Plaintext
go-tour = active

The old release is still retained:

Plaintext
/data/go-tour/releases/20260811-zh-CN-925d59d

For quick rollback when needed.


17. From “Translation Complete” to “Truly Ready for Public Use”

This phase gave me a very clear feeling:

Having all 103 pages translated does not mean the project is truly complete.

Once it is truly facing public users, you must continue to handle:

  • Project identity;
  • Homepage entry;
  • Public navigation;
  • Footer;
  • ICP filing;
  • Cross-linking between GitHub and development records;
  • production metadata;
  • Release package;
  • File permissions;
  • systemd;
  • Atomic switching;
  • Rollback;
  • Origin server acceptance;
  • CDN;
  • Browser cache;
  • Development and production state boundaries.

Many of these things do not fall under “translation,” yet they directly determine whether this project is ultimately a publicly accessible service that can be maintained long-term.

This is also why I ultimately did not make go-dev just a page where “you open it and see the tutorial”.

It now truly assumes the role of:

Entry point for the community multilingual translation project of official Go learning materials

A Tour of Go Simplified Chinese is just the first phase.

If new languages or new official Go learning materials are added in the future, the homepage, release metadata, and production deployment structure organized this time can all continue to be reused.

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

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

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

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

关于我  ·  GitHub  ·  邮件联系