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

Localizing A Tour of Go: From Code Comments to a Complete Multilingual Learning Experience

Figure 4: Translated Playground Example, showing Chinese comments and the unchanged Go code structure.

作者:

在

From Course Text Translation to a Complete Learning Experience

The initial focus of the A Tour of Go multilingual translation project was on the course pages themselves.

The project uses an entire page as the minimum translation unit:

Plaintext
Complete present.Section
        ↓
Translation
        ↓
Structure validation
        ↓
Page publishing

This approach ensures that the course content on the left is fully localized.

However, during actual use, I discovered a problem:

The comments in the Playground example code on the right remained in English.

For example:

Go
// Create a huge number by shifting a 1 bit left 100 places.

// In other words, the binary number that is 1 followed by 100 zeroes.

// Shift it right again 99 places, so we end up with 1<<1, or 2.

For beginners, reading the tutorial requires switching between the Chinese body text and the English code comments, resulting in an incomplete learning experience.

Therefore, the project further expanded the scope of translation to include Examples in the unified translation workflow.

Figure 1: Playground Example before translation, showing the issue where the right-side code comments remain in English.
Figure 1: Playground Example before translation, showing the issue where the right-side code comments remain in English.

Example as an Independent TranslationUnit

To avoid the risks associated with simple text replacement, the project does not treat Examples as ordinary strings.

By design:

  • Page is one type of TranslationUnit;
  • Example is another type of TranslationUnit.

Specifically:

  • The Page translation unit corresponds to a complete .article;
  • The Example translation unit corresponds to a complete .go file.

The project documentation specifies:

The Example translation unit is a complete .go file.

Additionally, the hash of the Example source covers the entire file:

Plaintext
source_sha256 covers all bytes of the file, not just the comments.

This ensures that:

  • Changes in code content can be detected;
  • The translation process does not focus solely on comment fragments;
  • Examples can be managed using the same workflow as Pages.
Figure 2: Example TranslationUnit design, showing the Example as a complete .go file serving as the translation unit.
Figure 2: Example TranslationUnit design, showing the Example as a complete .go file serving as the translation unit.

Using Go scanner to Protect Code Structure

The biggest difference between code files and plain text is that:

Only certain parts of the code can be translated.

For example:

Translatable:

Go
// Calculate the result

Cannot be modified:

Go
package main

import "fmt"

func main()

Therefore, the Example translation workflow adopts a specialized processing approach:

Plaintext
Go scanner
    ↓
Identify real comments
    ↓
Protect code, strings, layout, and other content
    ↓
Only expose natural language comment payload
    ↓
Restore complete Go file

In the specific implementation:

  • Use the Go scanner to identify real comments;
  • Replace code, strings, layout, comment delimiters, and machine-semantic comments with protection tokens;
  • Only allow ordinary natural language comments to be translated;
  • Use a unified glossary to maintain terminology rules.

This avoids:

  • Modifying Go identifiers;
  • Breaking string content;
  • Altering the code structure;
  • Causing the Example to fail to run.
Figure 3: Go scanner comment protection mechanism, showing code structure protection and natural language comment extraction.
Figure 3: Go scanner comment protection mechanism, showing code structure protection and natural language comment extraction.

Translated Playground Example

After completing the Example translation, the code structure remains unchanged; only the natural language comments are updated.

For example:

Go
// 将 1 左移 100 位,得到一个非常大的数。
// 换句话说,这个二进制数由 1 后跟 100 个 0 组成。
// 再将它向右移 99 位,最终得到 1<<1,也就是 2。

Meanwhile:

Go
package main

import "fmt"

func main()

and other code content remain as they are.

Final result:

  • The course text on the left is in Chinese;
  • The Playground comments on the right are in Chinese;
  • The example code still runs correctly.

This means the A Tour of Go learning experience has expanded from “course translation” to “complete tutorial localization”.

Figure 4: Translated Playground Example, showing Chinese comments and the unchanged Go code structure.
Figure 4: Translated Playground Example, showing Chinese comments and the unchanged Go code structure.

Example Translation Integrated into the Unified Publishing Workflow

Example is not a standalone temporary feature.

It shares the following with Page:

  • TranslationUnit management;
  • batch workflow;
  • validation;
  • Translation Quality Review;
  • promotion;
  • release projection.

Overall workflow:

Plaintext
Page / Example TranslationUnit
            ↓
export
            ↓
model translation
            ↓
process
            ↓
automatic validation
            ↓
Translation Quality Review
            ↓
promotion
            ↓
ready
            ↓
publish

This way, when expanding to more language versions in the future, there is no need to redesign the workflow for different content types.


Summary

Playground Example localization is an important step in the A Tour of Go multilingual translation project.

It solves more than just the translation of a few lines of code comments; it achieves the following:

  • Bringing Examples into the unified translation system;
  • Establishing a dedicated protection mechanism for code files;
  • Ensuring the translation process does not break the Go source;
  • Maintaining a consistent language experience between the course text and code examples.

Ultimately, the project achieved:

Plaintext
Course text localization
        +
Code example localization
        =
Complete learning experience localization

This also provides a unified foundation for supporting more language versions in the future.

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

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

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

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

关于我  ·  GitHub  ·  邮件联系