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

After Completing All 103 Pages of the A Tour of Go Multilingual Translation Project, I Finally Generated a Standalone zh-CN Production Bundle

Figure 3: The A Tour of Go Simplified Chinese page started independently from the production bundle, course text, public UI, and official Go examples have all entered the final release form.

作者:

在

In the previous phase, I completed all course translations, public UI localization, and pre-release global acceptance for the A Tour of Go Simplified Chinese zh-CN.

At that point, the project had achieved:

  • All 103/103 official course pages ready
  • pending=0
  • blocked=0
  • Titles and subtitles for all 7/7 .article localized
  • Public UI copy localized
  • HTTP acceptance completed for 103/103 course pages

However, this still cannot be considered a true “release”.

The ability to view the complete Chinese version in the browser previously relied mainly on the project’s preview process. This process is suitable for development, translation verification, and page inspection, but it should not be used directly as a production deployment method.

Therefore, the real problem to solve next became:

How can I generate an official release package from the 103 completed Chinese pages that can start independently, independent of the translation status directory, and is suitable for production use?

This was the main task of this phase.


1. From “Able to Preview” to “Able to Release”

During the previous development process, the project had already formed a fairly complete language projection workflow.

The main data sources included:

  • Frozen A Tour of Go upstream content
  • ready candidate for 103 official pages
  • Title and subtitle metadata for 7 .article
  • zh-CN public UI copy

They ultimately generate a localized _content through the existing complete projection logic.

Therefore, I did not redesign a so-called “production content generator” this time.

Instead, I chose to continue reusing the heavily validated:

Plaintext
BuildLocaleProjection

This means that whether during development preview or official production publish, the course text ultimately goes through the same projection and structural validation process.

This avoids a very dangerous situation:

One type of content is verified during development, while another independent set of logic regenerates a different set of content during the official release.

What this production publish does is essentially add a layer of official release capability around the already mature language projection.


2. First Solve the Go Code Execution Problem in the Production Environment

Before actually implementing publish, I found another issue that had to be resolved first:

How should the Go examples on the right side of A Tour of Go actually run in the production environment?

The local Tour originally used /socket.

The browser sends the Go code to the Tour service via WebSocket, which is then compiled and run by the Go toolchain on the Tour’s host machine.

There is no problem doing this in local development.

But deploying it directly to the public internet would mean:

Public users could submit code to my server, which would then compile and execute it on the server itself.

This clearly cannot serve as a production architecture.

Therefore, the project ultimately explicitly ruled out:

Plaintext
Public Tour
→ /socket
→ Local go build / execution

This route.


3. Re-adopting the Official Tour’s HTTPTransport Architecture

After further inspecting the frozen official upstream, I found that the official Tour’s production method was inherently different from the local mode.

The local environment uses:

Plaintext
SocketTransport

While the production environment uses:

Plaintext
HTTPTransport

After the user clicks “Run” in the browser, the call chain becomes:

Plaintext
Browser
→ HTTPTransport
→ /_/compile
→ Tour production proxy
→ Official Go Playground
→ Returns execution result

Ultimately, the remote Go Playground executes the user’s Go code, not the production server hosting the Tour.

Therefore, I ultimately adopted this solution as well.

In the current production runtime:

  • /_/compile is hard-coded to proxy to the official Go Playground
  • /_/fmt also uses the remote Playground
  • The backend parameter provided by the user cannot change the target address
  • /socket does not register any local execution handler
  • The production host will not execute user-submitted Go programs

Additionally, boundary limits such as request body size, response size, timeouts, and redirects were further enforced.

This allows the Tour’s core experience to be preserved:

Users can still modify code, format code, and directly click “Run”.

Without needing to build an entire code execution sandbox just to launch a Chinese Tour.


4. Officially Adding the production publish Command

After completing the production runtime, the next step was to actually implement publish.

The project can now run:

Bash
go run -mod=readonly ./cmd/tour-i18n publish \
    --locale zh-CN \
    --output <directory>

It executes the complete workflow:

Plaintext
Check output directory
→ Create staging
→ BuildLocaleProjection
→ Check 103/0/0
→ Build production binary
→ Write release.json
→ Generate SHA256SUMS
→ Complete verification
→ Atomically rename to official output directory

Finally, it generates:

Plaintext
<output>/
├── bin/
│   └── tour
├── _content/
├── release.json
└── SHA256SUMS

This no longer includes:

  • candidate
  • status
  • translation-runs
  • attempt
  • Other translation development statuses

In other words:

The official release package only carries what is actually needed to run the Tour.


5. First Official Generation of the zh-CN Production Bundle

To perform one more manual verification before actually deploying to the server, I regenerated a release package specifically for local acceptance.

The final result:

Plaintext
production bundle: /tmp/go-tour-zh-cn-blog-20260811
locale=zh-CN ready=103 pending=0 blocked=0 pages=103 articles=7

These numbers are quite representative for this phase:

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

This means all 103 official pages have entered the final release package, rather than still being mixed with pending or blocked pages.

Figure 1: Generating the zh-CN production bundle, all 103 official pages are ready, pending and blocked are both 0.
Figure 1: Generating the zh-CN production bundle, all 103 official pages are ready, pending and blocked are both 0.

6. The Release Package is No Longer Just a _content Directory

This time, I did not simply define “official release” as:

Copying the localized _content out.

Because what that generates would still depend on the source code repository to run.

The current bundle already includes an independent:

Plaintext
bin/tour

And the locale is fixed at build time to:

Plaintext
zh-CN

So at runtime, there is no need to provide:

Plaintext
--locale

Nor is there a need to specify:

Plaintext
--content

The binary will find the adjacent:

Plaintext
../_content

based on its own location.

This is something I value.

Because a true release package should not require deployment personnel to know the internal directory structure of the source code repository.


7. release.json: Recording What This Release Package Actually Is

Every production bundle will generate:

Plaintext
release.json

The actual content this time includes:

JSON
{
  "schema_version": 1,
  "locale": "zh-CN",
  "upstream_commit": "e11dacba76c5aae474746e9eedee19693f492803",
  "pages": 103,
  "articles": 7,
  "execution_transport": "http-playground-proxy",
  "execution_provider": "play.golang.org",
  "local_socket_enabled": false,
  "goos": "linux",
  "goarch": "amd64"
}

This records:

  • Release language
  • upstream commit
  • Number of pages
  • Number of articles
  • Code execution method
  • Playground provider
  • Whether /socket is enabled
  • Build target platform

At the same time, I deliberately did not write the following into the manifest:

  • Build time
  • hostname
  • Username
  • staging path
  • Absolute output path
  • Random ID

Because this information would cause the same source code to produce different files on every publish.


8. All 185 Files Undergo SHA-256 Verification

The bundle also generates:

Plaintext
SHA256SUMS

It covers:

  • bin/tour
  • All official files in _content
  • release.json

The actual release package verified a total of:

Plaintext
185

files.

Final result:

Plaintext
SHA256SUMS: all 185 files OK
Figure 2: Release manifest and integrity verification for the production bundle, all 185 files passed SHA-256 verification, local /socket is explicitly closed.
Figure 2: Release manifest and integrity verification for the production bundle, all 185 files passed SHA-256 verification, local /socket is explicitly closed.

In addition, I consecutively generated two bundles located in different directories.

When finally performing a directory comparison:

Plaintext
diff -r -q release-a release-b

There was no output.

That is, under the conditions of:

  • Same source code
  • Same Go toolchain
  • Same GOOS/GOARCH

all files from two publishes were byte-for-byte identical.

This is why I call this phase:

Deterministic production release package generation.


9. Starting the production binary from a completely unrelated directory

After all automated tests were completed, I did another manual test.

This time, I deliberately did not run the Tour from within the source code repository, but switched to:

Plaintext
/tmp

Then started it directly using the absolute path from the release package:

Bash
/tmp/go-tour-zh-cn-blog-20260811/bin/tour \
    --http 127.0.0.1:43999

Startup result:

Plaintext
serving locale zh-CN on http://127.0.0.1:43999 with remote Playground execution

This proves that the production binary does not depend on:

Plaintext
~/code/go-tour-i18n

as the current working directory.

Afterwards, I opened the browser, and the complete Chinese Tour displayed normally.

Figure 3: The A Tour of Go Simplified Chinese page started independently from the production bundle, course text, public UI, and official Go examples have all entered the final release form.
Figure 3: The A Tour of Go Simplified Chinese page started independently from the production bundle, course text, public UI, and official Go examples have all entered the final release form.

10. Manually Running Go Examples Again in the Final Release Package

It is not enough for the page to just open.

This time, I directly clicked:

Run

on the official example on the right:

Go
package main

import "fmt"

func main() {
    fmt.Println("Hello, 世界")
}

It successfully returned:

Plaintext
Hello, 世界
程序已退出.

This means the final release package is not just a static, read-only Chinese version.

It still preserves A Tour of Go’s most important interactive capability:

Read → Modify → Format → Run.

The only difference is that the production environment no longer executes programs via the local /socket, but through the remote Playground.

Figure 4: Production runtime successfully runs official examples via remote Go Playground, preserving A Tour of Go's interactive execution capability without exposing the local /socket code execution interface.
Figure 4: Production runtime successfully runs official examples via remote Go Playground, preserving A Tour of Go’s interactive execution capability without exposing the local /socket code execution interface.

11. Format Also Re-verified Manually

Besides Run, I also deliberately broke the code indentation and then clicked:

Format

The code formatted correctly.

Therefore, in the final manual acceptance:

Plaintext
Run    → Success
Format → Success

Both real interactive paths have passed.


12. One Last Check of /socket

Since the production runtime security boundary was a focus of this implementation, I finally made manual requests to a few paths on the running official bundle.

Results:

Plaintext
/socket                    → 404
/socket WebSocket Upgrade  → 404
/_/share                   → 404
/_/anything                → 404

The second item is particularly important.

Even if a WebSocket Upgrade request is explicitly sent:

Plaintext
Connection: Upgrade
Upgrade: websocket

/socket still returns:

Plaintext
404

This means the production runtime is not just “the frontend temporarily not using /socket“, but rather:

The server itself has not opened this local code execution path.

At the same time, the current Tour UI does not actually use Share, so:

Plaintext
/_/share

also explicitly returns 404 for now.

Unknown:

Plaintext
/_/anything

will likewise not erroneously fall into the Tour page routing and return a fake 200 HTML.


13. At This Point, “Production Release Capability” is Truly Complete

This phase ultimately resulted in two key commits.

production runtime:

Plaintext
98877f7 feat: Add secure production Tour runtime service

production publish:

Plaintext
e4a8fe0 feat: Add deterministic production release package generation

Subsequently, the README and project status were also updated:

Plaintext
8d2bf82 docs: Update production release completion status

So the project status has officially changed from the previous:

production publish not yet implemented

to:

production runtime completed
production publish bundle completed
final pre-release acceptance passed
actual production environment deployment not yet started

This distinction is still very important.

I now have a production release package that can truly be used for deployment, but the website has not automatically become “live” as a result.


14. Next Step: Actual Production Environment Deployment

Next, the project can finally enter the next phase:

Actual production environment deployment

What needs to be handled next is no longer translation algorithms or candidate verification, but more traditional production deployment issues, such as:

  • Server deployment directory
  • production bundle upload and version management
  • Process hosting
  • Nginx reverse proxy
  • HTTPS
  • Domain name
  • CDN
  • External access verification
  • Playground external network reachability
  • Final HTTP acceptance after official launch

I plan to document these separately.

Because from this point on, the nature of the problem has changed.

What was solved previously was:

How to reliably translate A Tour of Go into a complete Simplified Chinese version.

What this phase solved was:

How to turn the completed Chinese version into a deterministic, secure, and independently runnable production release package.

And what the next phase will solve is the true:

How to make it officially appear on the public internet.

At this point, the zh-CN first phase of the A Tour of Go multilingual translation project is just one step away from actually going live.

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

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

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

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

关于我  ·  GitHub  ·  邮件联系