English-Korean Developer Terminology and Glossary Discipline
Classify each term as English-kept or Korean-rendered, record it once in a governed glossary, and align UI labels, code comments, and error messages with the documentation.
The buyer question
Which developer terms should stay in English versus Korean, and how does a team keep that decision consistent across documentation, UI, and code?
The output here is a terminology consistency map that records, for every product concept, whether it stays in English or takes a Korean rendering and how that decision is enforced across each surface a developer reads. Assign the decision to the concept rather than to isolated sentences, store retained English forms and prohibited variants beside each entry, and then check that UI labels, code comments, and error messages match the documentation. Hong recommends treating the glossary as one governed source rather than a per-translator preference, so the same product object never appears under several plausible Korean names.
Reading the decision in context
What this decision actually asks of the team.
Decide the keep-English boundary first
Before rendering anything, draw a line between the terms that should stay in English and the terms that read more clearly in Korean. API identifiers, protocol names, product object names, and widely adopted technical tokens usually belong in English because a developer will search, type, and match them against the real interface, while conceptual and task-describing language often reads better rendered into Korean.
Write the rule down as categories rather than case-by-case instinct, because an unstated boundary is where inconsistency begins. When the category rule is explicit, a new term can be classified quickly and a reviewer can challenge the classification without reopening every earlier decision, which is what keeps a growing glossary coherent.
Keep one glossary as the source of truth
A term decision should live in exactly one place, attached to the product concept it names, with the source term, the approved rendering, the retained English form, a usage context, and the variants that are disallowed. Attaching the decision to the concept rather than to a sentence is what lets the same object stay consistent across a quickstart, a reference page, a diagram caption, and a troubleshooting note.
Tie that glossary to a product version and a named reviewer so it can evolve without fragmenting. When a new concept enters the product, it earns an entry before it appears in translated material, and any deliberate exception is logged with its scope, so the glossary stays ahead of the content instead of being reconstructed after drift has already spread.
Align UI labels, code comments, and error messages
Documentation is only one of the surfaces a developer reads. The label on a screen, the comment inside a sample, and the wording of an error message all name product objects too, and when those surfaces disagree with the docs the reader is left guessing whether they describe the same thing. Each of these surfaces should be checked against the same glossary entry rather than translated in isolation by whoever happened to touch it.
Separate the fixes by ownership as you go. A phrasing change in prose can stay with editorial review, but a UI string or an error message is product text that engineering must change, so the audit should record the exact location and the correct term and route it to the owner who can actually alter that surface.
Avoid the mistranslations that recur
Some terms are reliably mistranslated, and naming them in advance is cheaper than catching them later. Polysemous English words, verbs whose meaning shifts with context, and words that carry both a casual and a precise technical sense are the usual offenders, and a natural-sounding Korean rendering can quietly denote the wrong concept while reading perfectly well.
Maintain a short watchlist that pairs each risky term with the tempting-but-wrong rendering and the approved one. This gives a reviewer something concrete to check against, turns a vague instinct that a translation feels off into a specific comparison, and prevents the same inaccurate choice from reappearing every time a new writer encounters the term.
Treat the glossary as discipline, not authority
The linked GraphQL and distributed-tracing pages are technical artifact examples that show how Hong keeps schema, request, and observability terminology connected within one explanation. They are not an official term standard, a certified translation, or evidence about how the wider Korean developer market prefers to name things.
A consistency map earns its value by keeping one product's language coherent for a bounded set of assets, and product and engineering owners remain the authority on product-specific names, security wording, and any user-facing string. Hong can structure and audit the glossary, but the final naming of a product surface stays with the team that ships it.
The framework
Terminology Consistency Map
Hong recommends building one map that pins each product concept to a keep-English or render-Korean decision and then traces that decision into every developer-facing surface. The map keeps naming choices at the concept level, exposes retained English forms and banned variants, and gives reviewers a single artifact to check documentation, interface strings, comments, and error text against.
- A source term list or existing bilingual glossary, even a partial one
- The product UI string catalog with the labels a developer actually sees
- Code samples with their comments and any localized annotation
- The product error-message and log-message catalog
- Existing documentation and any previously localized technical assets
- A named bilingual reviewer who can approve or reject a term
- Style rules stating which categories of term are retained in English
Classify each term as kept or rendered
Sort every concept into keep-in-English, render-in-Korean, or render-with-English-in-parentheses. Keep established API identifiers, protocol names, and widely used technical tokens in English, and render conceptual or task language in Korean when a natural equivalent reads more clearly than a transliteration. Record the reason for each decision so it can be reviewed rather than reopened per sentence.
Define one governed glossary entry per concept
For each concept, capture the source term, the approved Korean rendering when one is used, the retained English form, a short usage context, and the variants that are not allowed. Attach the entry to the product object rather than to a phrase, so a term keeps one meaning across guides, captions, diagrams, and reference pages.
Align UI labels, comments, and errors with docs
Treat interface strings, code comments, and error messages as terminology surfaces, not afterthoughts. Confirm that a label the reader sees on screen, the word used in a sample's comment, and the phrase in an error message match the term the documentation uses for the same object, and flag every mismatch as a defect to resolve before publication.
Guard against common mistranslations
List the terms most likely to be mistranslated: polysemous English words, verbs whose Korean equivalent shifts meaning by context, and marketing-adjacent words that carry a precise technical sense. Record the wrong-but-tempting rendering beside the approved one so reviewers can catch a drift back toward the inaccurate choice.
Version the glossary and name an owner
Tie the glossary to a product version and a named reviewer who can approve or reject a proposed term. Log deliberate exceptions with their scope, and require that any new concept entering the product gets an entry before it appears in translated material, so the map stays ahead of drift instead of chasing it.
Audit consistency across every surface
Run a periodic pass that samples documentation, UI strings, comments, error text, and support articles against the glossary. Report each divergence as a concrete location and the correct term, and decide whether the fix belongs to editorial phrasing or to a product string that engineering must change.
- The full document-adaptation and task-flow delta workflow belongs in the technical-localization guide.
- Demo request and response reproducibility belongs in the API demo guide.
- First-run access and setup readiness belongs in the developer-onboarding checklist.
- Interpreting what evaluators say about wording belongs in the technical-feedback guide.
- Choosing whether terminology is even the first entry asset belongs in the entry-readiness guide.
Failure modes
Where this approach should stop or narrow the work.
Established English terms are translated anyway
A well-known API identifier, protocol name, or standard technical token is rendered into Korean or transliterated, and developers can no longer connect the documentation to the actual product surface. Mark these terms as retained English in the glossary and treat any Korean rendering as an error unless a reviewer approved it.
One concept uses different words per surface
The documentation names an object one way while the UI label, a code comment, or an error message uses another plausible term. The reader cannot tell whether the surfaces describe the same thing, so each surface must be checked against a single glossary entry rather than translated independently.
The glossary exists but nothing enforces it
A glossary is created once and then left behind while new content is written from memory. Without a named owner, a version tie, and an audit pass, the map silently diverges from the product and stops being a source of truth.
A polysemous term is rendered by the wrong sense
An English word with a precise technical meaning is translated by a general-purpose Korean equivalent that reads naturally but denotes something else. Record the tempting-but-wrong rendering beside the approved one so a reviewer can catch the drift before it ships.
Code identifiers get localized
A field name, parameter, or command inside a sample is rewritten to look more familiar, which breaks copy-paste and separates the sample from the documented API. Keep executable identifiers in their original form and localize only the surrounding comments with an explicit note.
Questions on this guide
Frequently asked about this decision.
Which developer terms should stay in English rather than be translated?
Keep terms a developer will search, type, or match against the real interface: API identifiers, protocol and product object names, command names, and widely adopted technical tokens. Render conceptual and task-describing language into Korean when a natural equivalent is clearer, and record the category rule so the boundary is applied consistently instead of case by case.
How do you keep one glossary consistent across many assets?
Store each decision once at the concept level with the source term, approved rendering, retained English form, context, and disallowed variants, then tie the glossary to a product version and a named reviewer. Audit documentation, UI strings, comments, and error text against it periodically, and log any deliberate exception with its scope so the map stays authoritative.
What if the UI label and the documentation use different Korean words?
Treat the mismatch as a defect and resolve it against a single glossary entry rather than picking a favorite. Decide which surface is wrong, record the exact location and the correct term, and route a UI or error-message change to the engineering owner who can alter product text, since those strings are not editorial prose.
How can a team catch common mistranslations before publishing?
Maintain a watchlist of terms that are reliably mistranslated: polysemous words, context-sensitive verbs, and words with both a casual and a precise technical sense. Pair each with its tempting-but-wrong rendering and the approved one, and have a bilingual reviewer check risky terms against that list rather than relying on how natural the sentence sounds.
Apply this recommendation
Share your product URL for a bounded Korea-facing next step.
Hong can use the product surface, current documentation, target evaluator, and Korea goal to recommend a practical first asset without implying official distribution or guaranteed adoption.
No Gmail? Open in your mail app or write to unduck2022@gmail.com.