When the multilingual translation project for A Tour of Go started expanding to Learn and Docs, I ran into a seemingly simple question:
Should different types of content share a single glossary, or should each maintain its own?
The most intuitive approach is actually to maintain them separately.
Tour has a Tour glossary.
Learn has a Learn glossary.
Docs has a Docs glossary.
This looks very clear.
Each content package manages its own content and its own terminology.
If a new technical term appears in Learn, it gets added to the Learn glossary.
If a new concept appears in Docs, it gets added to the Docs glossary.
Different packages do not affect each other.
From a short-term development perspective, this might even be the most convenient design.
But after actually starting work on v2, I increasingly felt that:
Although this design is easy to start with, it is hard to maintain in the long run.
Ultimately, v2 chose a different direction:
A single locale retains only one official glossary.
Tour, Learn, Docs, and any future content packages all share the same terminology governance results for a locale.
Why did the design end up this way?
Go terminology does not belong to a specific content package
The fundamental reason is actually quite simple.
A Go concept does not become a “Tour term” just because it appears in Tour.
For example, goroutine, channel, interface, method, and package—these concepts appear simultaneously in:
- Tour;
- Learn;
- Docs;
- Tutorials;
- API documentation;
- Other Go learning materials.
They belong to Go.
They do not belong to a specific collection of pages.
Building separate glossaries for different content packages means the same concept might be governed repeatedly.
For example:
Tour glossary
goroutine → goroutine
Learn glossary
goroutine → goroutine
Docs glossary
goroutine → goroutineThis looks fine.
Because the three places happened to decide on the same translation.
But the real trouble comes when things change later.
Suppose a term is reviewed again, and the standard is adjusted.
Then we need to keep asking:
Was the Tour glossary updated?
Was the Learn glossary updated?
What about the Docs glossary?
Have newly added content packages been synced as well?
At this point, terminology consistency is no longer guaranteed by the locale itself, but instead becomes:
Relying on multiple glossaries to stay in sync over the long term.
This is a very fragile state.
Multiple glossaries easily lead to “local correctness”
If each package independently manages its own glossary, the most common problem is not obvious errors.
Rather, it is:
Each glossary looks fine on its own, but the entire locale is inconsistent when put together.
For example, the same concept might use one translation in Tour for a long time.
In Learn, because a new terminology discovery was done, another expression is chosen.
When Docs is added later, it adopts a third expression.
Looking at each package individually, you might find reasons for each.
But end users do not care which internal package the content comes from.
Users see a single Chinese Go website.
If a concept is called A in Tour, B in Learn, and C in Docs, then from the user’s perspective, the terminology across the entire site is inconsistent.
In other words:
Content packages are engineering boundaries, but the locale is the boundary of the language experience.
This is another point I became increasingly certain of later on.
The glossary should follow the locale, not the package
Therefore, v2 ultimately placed the official governance boundary for the glossary at the locale level.
For example, there is only one official glossary for Simplified Chinese.
Tour uses it.
Learn uses it.
Docs uses it too.
When new content packages are added in the future, they will in principle continue to use the same one.
This does not mean different content lacks its own characteristics.
They certainly have them.
Tour often features pedagogical expressions.
Docs might be more formal and technical.
Learn might contain a lot of beginner-oriented explanations.
But these differences mainly belong to:
- Style;
- Context;
- Expression;
- Sentence structure.
They should not easily change the core terminology of the same Go concept.
Therefore, a more reasonable layering should be:
Locale
│
└── Unified Glossary
│
├── Tour
├── Learn
├── Docs
└── Future content packagesRather than:
Tour → Tour Glossary
Learn → Learn Glossary
Docs → Docs GlossaryIn the former design, terminology provides unified constraints downward from the locale.
In the latter design, continuous horizontal synchronization is required between different packages.
In the long run, I prefer to take on the complexity of the former.
But a unified glossary does not mean stuffing every word into it
There is also a problem here where it is easy to swing to the other extreme.
Since there is only one glossary for the entire locale, should we include every technical term that appears in Tour, Learn, and Docs?
No.
If we did, the glossary would quickly turn into something else:
A giant bilingual dictionary.
But the purpose of a glossary is not to record every English word that has ever appeared.
What it should actually manage is:
Terms that require stable decisions maintained across pages and packages.
For example:
Should a core Go concept be translated or kept in English?
If translated, what is the official translation?
Are there older translations that should not be used?
If a word has different meanings in general English versus a Go technical context, does it need to be clarified?
Which terms, if translated freely, are particularly likely to cause drift across the entire locale?
These are the problems a glossary should truly govern.
So a unified glossary does not mean infinite expansion.
Instead, it means deciding more carefully:
What is worth entering this set of rules shared across the entire locale.
Terminology Discovery and the official Glossary are two different things
This is another distinction that gradually became clear in v2.
Before actually deciding the glossary content, you can perform terminology discovery on a larger source corpus.
That is, you can continuously discover terms worth governing from:
- Tour;
- Learn;
- Docs;
- Future content;
The scope of discovery can be very large.
Because it solves the question:
What other words deserve our attention?
But the official glossary solves a different problem:
Which words are important enough to become long-term language rules for the entire locale?
The two should not be confused.
You can understand it as:
Large terminology corpus
↓
Terminology discovery
↓
Candidate terms
↓
Review / decision
↓
Unified locale glossaryIf everything discovered is written directly into the glossary, the terminology list will become increasingly bloated.
If the discovery corpus is not expanded at all, then every time a new content package is added, a batch of core terms previously never considered will suddenly be found.
So what v2 hopes to achieve is:
Let discovery look as far ahead as possible early on, but keep the official glossary restrained.
Why this is particularly important for future content packages
If the project only ever translated Tour, this problem would not be so prominent.
Because the corpus itself is relatively stable.
But once the project starts expanding to Learn, Docs, and more future content, the situation changes.
Suppose that every time a package is added, it goes through:
Discovering a large number of new terms
↓
Large-scale modifications to the glossary
↓
A large amount of existing translation becomes stale
↓
Re-review
↓
Adding the next package
↓
Large-scale modifications to the glossary againThen the entire project will experience obvious oscillation.
Every time the content scope expands, a large amount of already stable translation is affected again.
This is clearly not a long-term scalable state.
Therefore, another goal of terminology discovery in v2 is:
To understand ahead of time, from a larger corpus range, what core terms a locale will actually need in the future.
This does not guarantee that the glossary will never change again.
There is no need to pursue such an unrealistic goal either.
But it can at least reduce:
Rediscovering a batch of the most basic terms every time a package is added
This kind of avoidable oscillation.
After glossary changes, you cannot simply redo everything in bulk
Once the entire locale shares a single glossary, a more practical question immediately arises:
If the glossary changes, what happens to previously completed translations?
The simplest implementation is of course:
old glossary SHA
≠
new glossary SHA
↓
All TranslationUnits staleThis check is very easy to implement.
And it is very conservative.
But the problem is that the engineering cost is too high.
For example, suppose just one preferred term appearing in only two pages is added.
If this causes hundreds of TranslationUnits across the entire locale to be retranslated and re-reviewed, it is clearly unreasonable.
This is why, after unifying the glossary, the system cannot just compare an overall file SHA.
What really needs to be determined is:
What content is specifically affected by this semantic change in the glossary?
Which pages contain this term?
Does this change fall under mandatory, preferred, or another rule?
Does the old candidate already naturally satisfy the new glossary?
Which TranslationUnits are actually affected?
Which TranslationUnits can completely continue using their original high-quality results?
This later evolved into semantic compatibility and affected scope.
I plan to write about this separately in the next article.
Because I think it is itself another crucial issue after unifying the glossary:
A change in the glossary does not mean all historical translations become invalid together.
A unified glossary also reduces duplicate work
When first designing the glossary, I focused more on:
How to keep translation results consistent?
By v2, I increasingly felt that the glossary had another very important role:
Reducing duplicate decisions.
If a stable translation for the same term has already been confirmed through Generation, Reviewer, and even multiple rounds of actual translation verification, then when a new content package encounters it, there is no need to discuss it again.
For example:
Tour has already decided
↓
Unified Glossary
↓
Learn directly reuses it
Docs directly reuses it
Future package continues to reuse itThis is actually consistent with a direction the entire project gradually clarified later on:
Work that has already been completed to a high quality should be reused as much as possible.
It is not just the translations themselves that can be reused.
Stable terminology decisions should also be reused.
Otherwise, as the number of content packages grows, duplicate decisions will also increase.
This does not mean the glossary can never be modified
A unified glossary is not a file that is permanently frozen once determined.
Language itself evolves.
The project will also constantly encounter new contexts.
Sometimes a term that seemed reasonable early on might expose problems in a larger corpus.
Sometimes a translation that is unambiguous in Tour turns out to be unable to cover a more formal technical context when entering Docs.
In such cases, the glossary should of course be modified.
The key is not:
Never change.
But rather:
Every change should have a clear linguistic reason, and it should be possible to determine what this change actually affects.
This is more realistic than simply pursuing a “forever stable glossary”.
What truly needs to be stable is the governance method.
Not a specific file remaining untouched forever.
Why not put package-specific terms into a separate glossary
There is also a seemingly more compromise design:
The locale has a global glossary,
and each content package then has its own local glossary.
This design is also very common.
But in this project, I ultimately did not choose it.
One reason is:
Once multi-layer glossaries are allowed, priority issues quickly become complicated.
For example:
locale glossary:
interface → 接口And then in a certain package:
package glossary:
interface → 界面Which one takes priority?
If overrides are allowed, which set of rules should the reviewer follow during review?
If the package glossary only uses another expression temporarily due to a special context, does it belong to official terminology rules, or is it just a natural language judgment within a TranslationUnit?
Once this boundary is opened, it is easy to regress to:
Multiple partially overlapping terminology authorities existing within the same locale.
So v2 prefers to keep the official glossary unique.
Issues that truly belong to contextual expression are left to linguistic judgment within the complete TranslationUnit.
If a difference is indeed stable, important, and worth long-term governance, then its conditions and meaning should be clarified back in the unified glossary, rather than creating a new official glossary.
One glossary per locale is essentially about establishing authority
In the end, I feel that the truly important part of this issue is no longer:
How many YAML files should there be?
But rather:
When different content has different opinions on the same term, who is the ultimate authority?
If Tour, Learn, and Docs each maintain their own official glossary, then there are actually multiple authorities.
And having only one official glossary per locale means:
Official terminology decisions for the same locale come from a single source.
Content packages can provide new corpus.
Terminology discovery can continuously find new candidate words.
Generation can expose new translation issues.
Reviewers can also find that old terms are not ideal in new contexts.
But the final official decision still returns to the same locale glossary.
This way, the entire system’s language governance chain becomes clearer.
The principles v2 ultimately chose
Looking back now, this part of the design can actually be condensed into a few very simple principles.
First:
Terminology belongs to the locale, not to a content package.
Second:
Terminology discovery can cover an increasingly large corpus, but the official glossary should remain restrained.
Third:
New content packages should reuse existing high-quality terminology decisions as much as possible, rather than redoing them.
Fourth:
The glossary can evolve, but every change should be able to precisely determine the content actually affected.
Therefore, a locale ultimately retains only one official glossary.
The addition of Tour, Learn, Docs, and future content packages should not cause terminology authority to be constantly duplicated.
They should continuously expand our understanding of this locale.
But ultimately, they still converge into the same language standard.