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:
Complete present.Section
↓
Translation
↓
Structure validation
↓
Page publishingThis 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:
// 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.

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
.gofile.
The project documentation specifies:
The Example translation unit is a complete
.gofile.
Additionally, the hash of the Example source covers the entire file:
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.

.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:
// Calculate the resultCannot be modified:
package main
import "fmt"
func main()Therefore, the Example translation workflow adopts a specialized processing approach:
Go scanner
↓
Identify real comments
↓
Protect code, strings, layout, and other content
↓
Only expose natural language comment payload
↓
Restore complete Go fileIn 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.

Translated Playground Example
After completing the Example translation, the code structure remains unchanged; only the natural language comments are updated.
For example:
// 将 1 左移 100 位,得到一个非常大的数。
// 换句话说,这个二进制数由 1 后跟 100 个 0 组成。
// 再将它向右移 99 位,最终得到 1<<1,也就是 2。Meanwhile:
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”.

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:
Page / Example TranslationUnit
↓
export
↓
model translation
↓
process
↓
automatic validation
↓
Translation Quality Review
↓
promotion
↓
ready
↓
publishThis 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:
Course text localization
+
Code example localization
=
Complete learning experience localizationThis also provides a unified foundation for supporting more language versions in the future.
