How People Translate Quickly | Design Tokens Format 2025.10: Translate Design-System Descriptions Without Breaking Token References

To translate a design-token library quickly, extract the human explanations from $description fields, preserve token paths, $value, $type, references and extension objects, and test the exported designs in every required locale. Design Tokens Format 2025.10 supplies a shared exchange structure, not an automatic multilingual-description mechanism. A safe team keeps one canonical token graph and manages reviewed descriptions through an explicitly documented localization layer.

Teams looking for design tokens translation, DTCG localization, or design-system description QA often encounter a confusing file: descriptive English alongside names that look like prose and JSON properties that definitely are not prose. Translate the purpose of a button color, but do not casually rename the token key that dozens of applications import. A style guide’s readable language and a design system’s machine-readable contract require different permissions.

This guide develops that boundary through example fixtures, alias resolution, accessible design language, release comparisons, failure diagnosis and a new-context exercise with a worked answer. The Design Tokens Community Group’s 2025.10 Format Module describes $description as an optional plain JSON string; it does not prescribe a built-in translation map there. All alternative multilingual storage patterns discussed below are integration designs that require agreement between the producer and consumer, not automatic support promised by the standard.

Establish the exact translation boundary

Why a token is not a normal sentence

A design token has a named path, a value and a type. The path may be written in English-looking segments such as action.primary.background, but components resolve it as a stable identifier. Translating that path can make a compiled theme refer to a nonexistent property even when the resulting words look friendlier. Human-readable descriptions are a separate layer of meaning.

A designer may request a Mandarin design-system handbook while developers keep using action.primary.background. That is a sensible brief: the handbook can show the approved Chinese explanation of the color’s purpose while the token object remains unchanged. The visual result must still be computed from the original typed color value, not from translated prose pasted into code.

Diagnose the initial file by comparing each string’s function. A sentence explaining when to use a token is editorial copy. A referenced path, file name or property starting with the reserved dollar sign is a structural instruction. Mark these classes before assigning translators, and ask a build engineer to export the baseline token map for later comparison.

Define what counts as a finished translation

A successful translated description tells a reader what decision the token supports, its intended use and meaningful exceptions. It does not merely substitute dictionary words for primary, muted or danger. In a design system, those terms may be roles with established definitions, so the documentation should explain the role within a real interface.

Suppose the English description says a color is for destructive actions, not ordinary warnings. A loose translation meaning “important red color” loses the distinction between deleting data and reporting an error. A reviewer should inspect both a Delete button and a validation warning before accepting a proposed translation, because the screen shows whether users can act safely.

Write measurable acceptance criteria: the complete source token graph still resolves; each required locale shows an approved purpose description; assistive text and printed style guides preserve distinctions among action roles; missing translations use the declared fallback. Capture a screenshot, a serialized values report and a terminology decision for the approved version.

Understand the Format Module rather than guessing

The meaning and limitations of description

The 2025.10 Format Module describes $description as a plain string that tools may display in style guides, editor tooltips or generated code comments. It is not defined as a language-tagged JSON object. Replacing it with an arbitrary dictionary of locales could break consumers that expect a string and should not be presented as conforming behavior.

An English file may contain "$description": "Background for the primary action". A Chinese guide can supply a separate keyed translation record for this token path, but the canonical token should retain the expected JSON type. If the product has a vendor-specific localization mechanism, document its version and test consumers that do not know that extension.

A schema check can reject an invalid description type, but not a misleading translated explanation stored elsewhere. Keep two tests: one validates the standard exchange document, and another verifies the companion translation catalog against current token keys. The second detects orphaned entries and absent locales without misrepresenting them as Format Module compliance checks.

Type is data, not vocabulary

The $type field governs how a value is interpreted: for example, a color token is fundamentally different from a dimension token. A translator must not replace color with a localized word or replace the unit px because those strings are part of the format’s technical vocabulary. Displaying “color” in a translated UI is a different requirement from editing the token.

In a multilingual design console, the user can see a localized heading meaning “color” while the saved JSON continues to say $type: color. Export a sample from both interfaces and compare the structural fields byte for byte. If the export is changed, the translation boundary has leaked into a format parser or form serializer.

Repair such a leak by separating presentation labels from internal type enumerations and testing import into a second tool. Invalid typed values are not harmless cosmetic mistakes: the consumer may reject the file, infer a different visual effect, or silently substitute defaults. A valid translation therefore preserves the behavior of every typed token.

Preserve the graph of references

Alias resolution survives every locale

Token aliases express relationships among tokens. The string reference {palette.brand} is not ordinary text even when palette and brand resemble English nouns. The format’s path syntax depends on exact token names. Translating the reference can leave a component with an unresolved alias although the source values remain present in the file.

Consider a button token whose value refers to a shared brand palette entry. The English and Chinese style guides may describe the button differently to suit local terminology; neither should duplicate or rewrite the palette relation. If a palette color changes once, both guides must still describe the button whose computed color comes from the shared alias.

Record a graph snapshot mapping each token to resolved type, resolved value and referenced target before localization. Then regenerate that graph after importing the translated companion descriptions. A graph change is a technical regression; a wording change is expected. Resolve discrepancies with the source token owner rather than allowing a translator to patch references manually.

Group names and token paths belong to maintainers

Nested group keys organize the token namespace, and an alias may point across those groups. A localized interface can show translated group titles in navigation, but renaming group keys inside the source tree changes the names that consumers use. Even punctuation carries meaning because the reference syntax constrains characters available in names.

If a source group is feedback and a subgroup is negative, a translator might prefer a more natural phrase than a literal rendering. Store that phrase as presentation metadata while preserving the original path. A second developer might import only the standard token file without the glossary and still needs predictable values.

Check an exported token-key inventory before and after locale packaging. Flag additions, deletions or key substitutions for engineering review. If the design team actually intends to rename the namespace, handle that as a versioned migration with aliases and compatibility testing, not as a hidden side effect of linguistic review.

Keep numeric and visual meaning stable

Values are not examples to paraphrase

A color’s components, a duration’s unit and a dimension’s magnitude are data. Treat them as locked while translating the prose around them. Teams sometimes copy a color definition into a translated document and manually adjust it to improve contrast; that may be valid redesign, but it is a different workflow requiring accessibility review and design approval.

A duration token expressing 200 milliseconds cannot become 200 seconds because a translator saw a unit symbol and rewrote it. Similarly, a dimension using rem units depends on typographic context, not on the user’s language alone. Compare typed payloads as parsed JSON rather than visually comparing formatted strings, so whitespace differences do not create noise.

When an example seems wrong for a locale, open a design issue that identifies the visual reason and affected components. Preserve the released value until the owner approves a design variant. The translation project should capture such findings instead of inventing untracked overrides in a target language file.

Semantic color roles require explanation

Terms like success, critical, caution and neutral are design roles rather than colors with universal emotional meanings. A translator needs the product context: is “critical” an irreversible action, a system outage, or a compliance warning? The correct description should help a designer choose the token consistently across buttons, badges and alerts.

Imagine an admissions form with a red border around an invalid field and a red button that permanently removes an application. A description that calls both “error red” erases a difference with real consequences. The reviewer should inspect neighboring text, iconography and state changes to decide whether the translated purpose supports the right use.

Create a glossary containing role, approved local phrase, forbidden misreadings and screenshot examples. Review it with accessibility specialists because color is not the only cue. The glossary can change when a product evolves, but the associated token identifier remains stable until a separate technical migration occurs.

Build a translation catalog outside the core format

Prefer a controlled companion table

Because $description is a single string in the exchange format, a project can maintain translations in a separate record keyed by stable token path and locale. Such a table is an application convention, not an official DTCG feature. Define precedence: the authored English description remains the baseline, with translated descriptions selected by the consuming documentation tool.

An illustrative table might map action.primary.background to en and zh-Hans descriptions. The table should never translate the key itself. A renderer can join by exact path and choose a locale based on reader preference, with a stated fallback when a translation is missing. It should also show whether the source description has changed since translation approval.

Validate that each translation row references an existing token and contains a valid language tag. Detect duplicate keys for the same locale, empty strings and stale approvals. When a token is deleted, archive its descriptions instead of silently assigning them to a new token with a similar name; that prevents accidental semantic reuse.

Vendor extensions are not universally portable

The format permits $extensions for vendor-specific information and expects tools to preserve unfamiliar extension data. A team could place localization metadata inside a documented extension namespace, but interoperability is conditional: another tool may preserve the data without displaying it. Do not imply that any consumer automatically understands a custom language map.

For example, a company-specific extension may carry a reference to a translation-bundle identifier rather than the translated content itself. A style-guide generator recognizes that convention; a second design application does not. Both can still exchange the core token values if they respect the standard, while the specialized renderer handles its extra metadata.

Test three operations separately: initial import, save-and-reopen in an unfamiliar tool, and documentation export through the intended renderer. If an extension is dropped or serialized incorrectly, the toolchain needs a contract fix. Never solve that problem by changing standard fields into unrecognized shapes.

Translation memories need version discipline

Match terminology by usage, not key alone

Translation memories can accelerate repeated design-system descriptions, but similar English strings may belong to different interface behaviors. “Primary” may describe a main action, a font family or a navigation level. A fuzzy match is a suggestion, not evidence of equivalent function. The translator should see the token role and product screenshot before reuse.

A previous translation for “secondary action background” may look safe when the next string is “secondary text background.” One refers to an interactive control; the other could describe content contrast. Reusing the phrase without review can instruct designers to apply a control style to a paragraph, damaging readability and consistency.

Store the memory entry with semantic role, source revision, target locale and approval reason. When a new token appears, group candidates by role before string similarity. Reviewers should prioritize high-impact tokens used in destructive interactions, focus indicators and content readability, even if those descriptions are short.

Source change invalidates approval selectively

An English description may change because the design team has clarified an exception, not because the token’s name or value changed. A target translation approved last week can become wrong today even when the alias graph still passes. The content workflow needs source-text version tracking independently from structural version tracking.

Suppose the original says a muted color is suitable for supplementary captions, while a revision says it must never carry essential instructions. If the Mandarin description retains the old recommendation, readers may use a low-contrast role for critical information. A checksum of the English description can identify rows needing renewed review.

Do not invalidate every language blindly after any file change. Compare the actual source descriptions and owner decisions. Keep unaffected rows approved, escalate changed risk-bearing instructions, and document exactly when a translation is refreshed. This selective approach is efficient without weakening quality assurance.

Inspect actual interface contexts

Tooltips impose space and clarity limits

A description may appear in a tiny editor tooltip, a large website table or a generated code comment. These views have different space constraints. A natural translation that fits a handbook might be unreadable in a tooltip. The remedy is usually to design a separate short label and full explanation rather than truncate a critical distinction.

In a token picker, the phrase “Use only for destructive actions after explicit confirmation” may wrap beyond the panel. A shortened label such as “Destructive action” can work if the longer condition remains accessible elsewhere. Test keyboard focus and screen-reader announcement so the shortened display does not hide essential context from nonvisual users.

Record the exact interface surface for each description, then inspect the longest target-language text. Count visible lines and check clipping under zoom, not just the number of Unicode code points. If the product needs short and long variants, make that a documented companion-catalog requirement rather than overloading $description with ad hoc delimiters.

Right-to-left language changes layout assumptions

Arabic and Hebrew documentation may reveal directionality problems unrelated to the underlying token values. A tooltip could reorder embedded Latin identifiers or unit abbreviations; a copied alias might become visually confusing. The text layer should handle bidirectional isolation while preserving the literal token path used for code and inspection.

If a documentation line contains an Arabic instruction beside {palette.brand}, the identifier must remain copyable exactly as written. A visually reversed brace sequence can cause human errors even when the JSON is technically correct. Test rendering, copying and pasting into a parser from the actual target interface.

Use directional markup at the presentation layer and a tested code style for literals. Do not insert invisible direction-control characters into token names or JSON references to make a screenshot look better. That approach turns a readability problem into a hard-to-find structural mismatch.

Check accessibility language alongside values

Contrast notes must name conditions

A description may say a color meets contrast needs, but contrast depends on foreground, background, size and state. Translating a broad claim into an absolute guarantee is risky. The translator should preserve any conditions, such as usage only with a particular text color or in a specified state.

An English description might say “intended for nonessential decorative borders.” A target translation that calls it “accessible border color” suggests the value works for all uses. The designer may then choose it for a form error indicator where the signal is essential. That is a change in design guidance, not a harmless lexical improvement.

Ask an accessibility reviewer to identify what a reader could infer from the translated claim and compare it with tested token combinations. Include screenshots at normal and enlarged text settings. When the original guidance is insufficient, request clarification from the design owner instead of inventing numerical compliance assurances.

Focus and state labels need exact distinctions

Focus, hover, selected and disabled states are related but not interchangeable. Translation memories may collapse them into a generic word meaning highlighted. This can cause a designer to reuse the wrong token and make an interactive control harder to navigate for keyboard or assistive-technology users.

Take a tab component: a keyboard-focused tab may not yet be selected, and a disabled tab is not an active selection. The descriptions for tab.focus.ring and tab.selected.background should convey the distinction even if the local language requires longer phrases. A reviewer should navigate the widget to see each state.

Test every state transition in a component showcase and pair the displayed translated explanation with the actual token used. If the wording cannot distinguish a state, add a local usage note in the companion catalog. Do not alter token names to compensate for a documentation vocabulary problem.

Control changes across multiple teams

Design and engineering need separate signoffs

The person who approves a natural translation may not know whether a property is a reference, typed value or export key. Conversely, the developer who validates JSON may not know whether the target phrase describes a destructive action correctly. A credible release requires both kinds of review, with evidence that each reviewer examined the right artifact.

In a multilingual university portal, a terminology reviewer checks whether “submission withdrawn” is understandable to students, while an engineer confirms that the token key still points to the same color across devices. Their responsibilities intersect only at the user experience. A green status on one review must not silently imply that the other passed.

Use a compact signoff table with language, translation revision, token graph revision, screenshot evidence and outstanding exceptions. Block the release if a required check is incomplete. This is not bureaucracy for its own sake: it tells the next maintainer whether a reported problem concerns meaning, rendering or serialization.

Cross-product reuse can expose hidden conflicts

A shared token package may power a mobile app, an internal dashboard and a public web portal. The same description can appear in dramatically different contexts. A translation approved in a design tool may be exported into autogenerated documentation and become misleading when read without its original screenshot.

A “primary button” in a student portal might mean the main action on a page, while an operations dashboard may have several competing actions. The technical token remains shared, but the guidance should define the design role abstractly enough to travel between products or document the exceptions explicitly.

Compare the translated documentation in all important consuming surfaces, not merely in the original design tool. Where product-specific interpretation is essential, link to a usage guideline rather than rewriting the common token contract. Cross-product examples belong in the review fixtures.

Diagnose failure patterns before release

Missing descriptions should be visible, not disguised

A locale with missing descriptions can fall back to English, show a clear untranslated state, or suppress optional explanations, depending on policy. The dangerous outcome is to show English words under a Chinese locale tag without indicating fallback; that falsely suggests coverage and makes defect reports harder to interpret.

Suppose 80 percent of the token library has reviewed Chinese copy. A style-guide sidebar may display the remaining English descriptions seamlessly, so a release manager assumes the entire set is finished. The coverage dashboard should report completion by token role and risk level rather than only counting translation records.

Create a missing-key report grouped by usage severity. A missing decorative spacing note may be tolerable, but missing instructions for a destructive state require explicit release approval. Test fallback on one intentionally untranslated token to confirm that the actual renderer behaves as documented.

Similarity checks should detect semantic drift

A spelling checker can confirm that a translated description has no obvious typos while missing the fact that “must not” became “should.” Such modal changes alter design guidance. A QA system should compare claims, constraints and exceptions, especially for risk-bearing tokens such as disabled actions, validation errors and status indicators.

The source says “not suitable for body text,” but the target says “suitable for body text.” Both are grammatical and may share most words. A reviewer working only from the target sentence cannot detect the reversal. Highlight negations and review the token’s actual use in a component before release.

Use targeted bilingual spot checks for quantifiers, exclusions, prohibitions and state distinctions. Record corrected defects in the terminology notes so translators do not repeat them in future descriptions. General machine similarity scores are screening signals, never substitutes for reading the technical claim.

Keep documentation exports reversible

Source files must remain reconstructable

An offline translation bundle should let an engineer regenerate exactly the canonical token export and a separate localized guide. Avoid editing vendor exports directly because the next build may overwrite those changes or mix target-language descriptions into the source of truth. Reproducibility allows reviewers to identify which layer caused a regression.

Set up a pipeline that validates the source Format Module JSON, resolves aliases, loads approved companion descriptions and renders a guide. Store the versions of the source and translation bundle together. A localized PDF should be treated as generated evidence, not the only surviving source of translated wording.

Test a clean rebuild in another environment, ideally one without local editor caches. Compare output token values with the English baseline and inspect several translated snippets. If the file is not reproducible, address missing dependencies or undocumented transformations before approving further languages.

Use change logs to prevent stale screenshots

Documentation screenshots can outlive the token values they depict. A translator may preserve a precise description while the actual button has changed state styling in a later build. That creates a misleading example even though the target words are faithful to the previous source.

If the focus ring changes from a solid line to a thicker outline, an old screenshot may instruct designers to look for the wrong visual marker. Record the component version used for the screenshot and regenerate it when visual tokens or components change. Review text and image together for target-language readability.

Use a release manifest with source commit, translation revision, screenshot build and validator version. When any part changes, flag affected examples. A good release makes it possible to reproduce a reported discrepancy without guessing which tool’s local cache produced the image.

Test a concrete compact fixture

Separate canonical tokens from translated explanations

The following fixture models one canonical Design Tokens Format document. It uses a simple dimension token and an alias; the translation catalog shown afterward is a separate product convention, not a standard property. Because the values are untouched, both descriptions can explain the same spacing relationship without changing the rendered layout.

An engineering test should parse the token JSON and verify that space.button still resolves to space.base. A language review should independently compare the Mandarin explanation with its English reference and the button screenshot. Passing JSON parsing alone will not tell anyone whether “padding” has been confused with “margin.”

The fixture intentionally avoids inventing a multilingual $description object. If a library consumes the companion catalog, the renderer must join by the stable path and interpret the BCP 47 tag. If no renderer is configured, the canonical file still works and the translation data remains available for documentation generation.

A syntactically valid token example and a separate translator catalog

The following JSON object illustrates a source token file in which one dimension token is aliased by a second dimension token. The object keeps $description as a string, while $type, $value, the token paths, and the alias expression remain technical data. This is a small structural illustration, not a full conformance or resolver test; the producer must check compatibility with its actual tooling.

{
  "space": {
    "base": {
      "$type": "dimension",
      "$value": {"value": 8, "unit": "px"},
      "$description": "Base spacing step used across the interface"
    },
    "button": {
      "$type": "dimension",
      "$value": "{space.base}",
      "$description": "Space around the button content"
    }
  }
}

A localization service may maintain a separate application-defined catalog keyed by the same two token paths; this catalog is not a DTCG Format Module object. Keeping the file outside the canonical token payload avoids confusing a translation mapping with a supported $description value type. A validator should require exact path matches between the exported token set and the localization entries, then compare resolved dimension values with the baseline.

{
  "locale": "zh-Hans",
  "descriptions": {
    "space.base": "在整个界面中使用的基础间距单位",
    "space.button": "按钮内容周围的间距"
  }
}

Verify unchanged structure and changed copy

A minimal automated comparison can serialize only technical fields and token paths, then compare the source and localized build. It should ignore intentional documentation changes while failing on any altered alias, type or value. A second script can check that every translated description has a corresponding source token and contains a reviewer-approved locale.

Do not rely on raw file hashes for this distinction. The localized documentation naturally has different bytes from the source, and JSON serializers may reorder keys without changing meaning. Compare parsed structures at known paths and keep separate text-change reports. This makes failures actionable instead of flooding a review with harmless formatting differences.

For a human proof, open both style guides at the same component and explain why the button uses the referenced spacing token. If the explanation changes behavior, return the wording to review. If only the language changes, the technical comparison must still pass. Together, those tests demonstrate the core promise of localization without data alteration.

Changed-context transfer exercise with worked answer

A shared design-system update

A school adds a new high-contrast theme, while the existing English and Mandarin guides describe a primary button that uses space.button as an alias of space.base. The design team proposes changing the actual base dimension in a new theme, and a translator suggests changing the Mandarin description to say the spacing is “always sixteen pixels.” What should the release owner approve first?

The answer is to reject the absolute “sixteen pixels” claim unless the computed result truly has that value for every supported context. Keep the alias and the typed dimensions in the canonical design-token source under engineering control. Resolve each theme using the appropriate mechanism and capture the resulting values. Then translate the role of the spacing token, not an incidental measurement that changes when themes or typography change.

For a transfer test, add a third locale and a mobile consuming application. Build the source graph once, check its technical invariants in all outputs, and inspect descriptions in the actual mobile token picker. The correct solution permits different displayed words and layout lengths but not different token identities or accidental alias substitutions. A release should explicitly report any untranslated note or unsupported extension instead of declaring the whole design system localized.

Summary and practical handoff

Design-token translation is successful when users can understand the purpose and limitations of each token while every machine-consumed name, type, alias and value still means what it meant before. The Design Tokens Format 2025.10 specification gives a disciplined exchange model; the team must deliberately design language selection and translated documentation around it. That separation saves debugging time and prevents friendly wording changes from becoming accidental visual regressions.

The practical handoff is a canonical token inventory, a locale-keyed companion description catalog, a glossary of design roles, a values-and-alias comparison, screenshots of important states and a signed review record. A second engineer should be able to regenerate the result, while a second translator can understand why a particular phrase was approved. Neither should need to change the token graph to solve a language problem.

Advanced diagnostics for production token libraries

Case study: one alias, three consuming exporters

Imagine a design team exporting the same token package to CSS custom properties, native mobile resource files and a design-tool catalog. All three consume stable paths but not necessarily the same human-facing description. A naïve localization script scans each exported file for English-looking phrases and changes them independently. The result is difficult to reconcile because each exporter may escape punctuation, shorten names or omit properties. Instead, localize the approved source descriptions in a companion catalog and use stable source token paths as the join key before export.

The CSS compiler might expose --action-primary-background, the mobile tool might produce actionPrimaryBackground, and the design editor might show “Primary action background.” None of these presentation forms should be the authoritative translation-memory key. Build a trace table that maps each output back to the source path. If the Mandarin tooltip is wrong, trace the display renderer and its translation record rather than patching compiled CSS. Repeat the comparison after minification, because name changes introduced by a build transform must not change the evidence about what was translated.

Case study: an apparently harmless slash in a path

A designer writes a documentation heading using the phrase “surface/raised.” A translator interprets the slash as a synonym separator, converts the visible label to a longer phrase, and then accidentally copies that phrase into an alias field. Since alias syntax refers to precise token names, this can break a dependency far from the edited documentation screen. The danger is not the slash itself; it is a workflow in which a free-form editorial field and a machine-consumed string share the same editing control.

Separate editable properties in the translation interface. Hide or lock technical paths and provide a read-only “source path” column for context. If an engineer needs to edit an alias, require a different review route with regression fixtures. This avoids a predictable class of errors in which strings look identical in a spreadsheet but have different operational meanings. To diagnose an existing fault, compare the parsed source path, the compiled output key and the resolved target; a missing edge identifies a structural problem rather than a lexical one.

Case study: font family names in a translated handbook

A token may describe a font-family stack, and the value can contain names that are recognizable words. A handbook translator might try to translate the family name itself, especially when it resembles an ordinary adjective. That changes the resource being requested, not the explanation of why the typeface was chosen. Font availability and fallback ordering are technical behaviors; a local edition may need a new font stack, but that needs type-design and product testing beyond linguistic approval.

Keep the $value font-family names and fallback order fixed in the translation-only release. Explain in the local guide which scripts the chosen font stack supports and where further fallback might occur. If Chinese glyph coverage is poor, file a separate locale-design requirement and test it with sample text, weights and numbers. Do not substitute font names in token JSON simply because the locale has changed. The correct test includes glyph rendering, layout measurements and a documented decision about whether the change is translation or a design variant.

Case study: generated code comments carry stale guidance

Some tools convert $description to source-code comments. A translated comment may be linguistically excellent but inserted into a generated file that is checked into version control. When the canonical description changes, a developer may trust the stale local comment without realizing it refers to an earlier release. A strong process therefore ties generated comments to a source-description revision and marks the generated file as an artifact, not an independently editable place to fix language.

During review, compare two builds that use different translation-catalog revisions while holding the token source constant. Only comment text should differ. Then hold the catalog constant and change a controlled source description; affected comment mappings should be marked stale until reapproved. This pair of tests reveals whether an exporter silently retains cached wording. It also gives developers an audit trail when a code review shows many translated comments but no actual token graph changes.

Case study: nested group descriptions across tools

A group may have its own $description explaining an entire family of tokens, while children carry descriptions of specific states. Translating the parent description alone cannot compensate for missing child distinctions. A renderer that flattens all tokens may discard parent guidance, and a renderer that shows a tree may overemphasize it. Both behaviors are plausible tool interfaces, so the language review needs the actual navigation structure, not just a flat list of strings.

For example, a parent group describes feedback colors while its child tokens distinguish success, warning and destructive actions. A target-language group description should name the family without implying that every color is interchangeable. In flat output, each child may need a self-sufficient explanation. Test both tree and flat views, and decide where usage restrictions should live. Duplicating restrictions as generated guidance is acceptable if controlled centrally; independently translating overlapping copy makes future revisions inconsistent.

Case study: visual regression catches the wrong bug

A visual comparison between an English handbook and a Chinese handbook will naturally show changed text widths, line breaks and sometimes panel heights. A simplistic screenshot-diff pipeline may report hundreds of failures and distract the team from one actual problem: a color swatch changing because a value was overwritten. Classify expected localization differences before interpreting the visual diff. Text reflow is not equivalent to changed token semantics, and changed semantics are not excused by passing linguistic review.

Use parsed-value comparisons for the technical contract and component screenshots for the experience. Compare swatch pixels only in regions intended to remain visually identical, and inspect text regions for clipping, directionality and interaction. Save the mask and baseline settings with the report so a second reviewer can reproduce the judgment. If a translated screenshot differs because a browser substitutes a font, investigate locale typography separately. This division of evidence is more informative than one enormous pass-or-fail image score.

Case study: design tokens embedded in educational worksheets

An education publisher may use design tokens to theme web lessons and printable worksheets. A spacing token could determine room for pupils to show mathematical working, while a semantic color token might mark model answers. Translating descriptions into Tamil should clarify the teacher’s intended use without silently shortening answer space or changing the visual distinction between prompt and solution. The user-facing explanation and the pedagogical meaning both deserve a review.

Build a worksheet fixture in each required locale with long vocabulary words, multi-line numbers and screen-reader labels. Keep the token graph unchanged for the translation-only check, then review whether the language requires a separate approved layout variant. A cramped answer box is a layout defect even if the phrase describing the token is perfect. Distinguishing the causes prevents a translator from being asked to repair a measurement by making the wording inaccurate or from editing numerical token values without design signoff.

Case study: source description includes a legal-looking guarantee

A source description may claim a token is “compliant” or “approved for all uses.” A translator who strengthens the phrase can create a false assurance, while a translator who weakens it may undermine intended restrictions. Neither task should be decided solely from dictionary equivalence. Ask the design owner for the exact underlying tests and scope of the claim, and preserve qualified language such as “when paired with,” “for decorative use” or “in tested components.”

If the claim cannot be substantiated, raise an editorial issue against the source before localizing it. Keep the original and proposed target versions in the review record rather than quietly replacing them with a stronger assertion. This matters when a design system is reused by external partners who may interpret documentation as a product guarantee. A useful translation does not manufacture compliance evidence; it describes the known behavior and the limits of those findings.

Case study: locale coverage is not one percentage

A dashboard can report ninety percent translation coverage while leaving the most consequential ten percent untouched. The high count might come from repeated decorative spacing descriptions, whereas focus, destructive-action and disabled-state guidance remains English-only. Measure not just whether a target string exists but whether the correct person approved it, whether the source changed since approval and whether the relevant UI surface was tested.

Group tokens into risk tiers based on what a mistaken choice would do. Decorative palette notes may use a documented fallback; instructions governing accessibility and irreversible actions may require verified local copy. Display the untranslated set by token path, role and last source revision. A project can then release a partial locale transparently instead of pretending all strings have the same importance. The report should avoid fabricated precision: its categories are locally defined governance choices, not percentages mandated by the token specification.

Case study: translating examples that contain code literals

A documentation sentence may combine ordinary words, an alias, a CSS property and an example value. The translator should be allowed to change the explanatory words while code literals remain protected. If a renderer builds these examples from Markdown, inline backticks and code fences can help separate the classes, but the export pipeline must preserve them. A copied code sample that contains localized punctuation can fail despite a flawless English-language version.

Test copy-and-paste of every sample from the localized guide into a parser or build step. Pay attention to smart quotes, full-width punctuation, nonbreaking spaces and bidirectional markers. A sample that only looks correct in a screenshot is not sufficient when the article teaches an executable workflow. Assign separate ownership to example code and explanatory copy, and require both a syntactic test and a meaning review before the document is marked ready.

Case study: responsible terminology across languages

A terminology choice may be natural in Singapore English but confusing in another English variety, and the same issue occurs across Chinese writing conventions or regional expressions. A single global translation memory can flatten legitimate differences. When a design system serves several regions, language tags, audience research and usage examples are needed to decide which target wording belongs where; the underlying token path remains the stable reference.

For a Singapore-facing school portal, describe “submit application” in terms familiar to local users rather than importing a phrase from an unrelated market. Review whether a target term names an action, a state or a component. Store the decision with its region and script context so it is not inappropriately reused elsewhere. If two locales use different phrases for the same role, that is not token divergence; it is controlled linguistic adaptation with shared machine semantics.

Case study: a translation vendor returns edited JSON

A vendor may return a copy of the complete token JSON with translated descriptions. Importing that file wholesale is risky because unrelated properties may have been reformatted, dropped or deliberately “improved.” Use a structured diff that accepts changes only in authorized description fields and rejects modifications to token keys, values, type declarations, alias targets and unknown extensions. Logging rejected modifications is more useful than silently overwriting them.

The importer should also check that every accepted translation corresponds to the source revision shown to the vendor. If the design system changed during translation, merge by stable key and source-text hash, not by array position in a spreadsheet. Test a malicious or accidental change to one value in a fixture and confirm the import fails closed. The final audit should state which fields were writable, which were ignored and who approved the accepted descriptions.

Release readiness: six final investigations

Confirm tokens with theme modes before translating claims

A token value may depend on a selected theme even though the exported guide displays one example. The Design Tokens Resolver Module discusses conditional sets and modifiers, but a resolver document is a distinct part of the ecosystem from the core token Format Module. A translation catalog must not assume that one sample value is always the resolved result. Review wording such as “always light,” “never changes” and “fixed width” against every supported resolution context.

A practical test enumerates approved theme inputs, resolves the same token paths and records the resulting values. The translated descriptions should communicate the role common to those contexts, while theme-specific deviations belong in explicit notes. If a new high-contrast context changes a color, that does not require changing the token key. It requires checking whether the original explanation is still true and whether users can see the variant without mistaking it for a new semantic role.

Investigate token name collisions at export

Two valid source keys may differ only by capitalization, yet an exporter targeting a language or platform can collapse them into the same output name. The Format Module warns about case-sensitive names and potential tool transformations. This is fundamentally a naming-collision issue; translation may reveal it when a localized guide produces shorter labels, but the language team cannot solve it by arbitrarily renaming the source token paths.

Compare the source inventory and generated target identifiers for uniqueness. If two keys map to one CSS variable or native resource name, stop the build and ask engineering to redesign the mapping or migrate the source names deliberately. A translated UI can distinguish two identically rendered labels by adding contextual descriptions. It cannot safely make two different technical tokens share one machine identity. Archive both the rejected transformation and the corrected export configuration for future releases.

Review numeric examples independently of descriptions

A handbook may show a token’s numeric value next to a translated explanation. Readers can mistake that value for a promise about every use, especially when a number appears in the same sentence as a design recommendation. Keep value display generated from the resolved token output rather than transcribed by translators. This avoids stale numbers in one language when a token or theme changes.

Test one dimension token with px units, one rem-based token and one duration token across the build. Ask a reviewer to distinguish the displayed numeric value from the usage instruction. If the target sentence claims a 200 millisecond animation is “instantaneous,” the problem is semantic accuracy, not numerical syntax. Correct the explanation using the actual interaction and audience expectation. Separate data displays, subjective experience descriptions and accessibility considerations in the documentation.

Decide how quotations and product names are handled

Some design descriptions quote visible button labels such as “Continue” or “Delete account.” Translators may need those examples to match the localized product, but they must not infer that the quoted string is a token name or that the button’s behavior changes with the language. Quotation marks can also be altered by typographic localization, so the example needs an explicit relation to the relevant product release.

Keep a mapping from sample UI copy to the approved interface string resource where possible. If the source application changes its label, update the documentation example through the same release process. A translator should not invent a button label that the application never displays. Test the example at the screen and locale stated in the guide, and note when it is illustrative rather than a guaranteed exact match. This avoids teaching designers to look for nonexistent controls.

Audit permissions in the translation interface

A well-designed translation form displays the locked token path as context and permits editing only approved natural-language fields. However, a permission mistake may expose the entire JSON object to a vendor. The danger increases when multiple agencies or contractors share a localization platform: some may not understand that a value-like string controls an application rather than a sentence.

Test permission boundaries using a sample vendor account. Attempt to alter $value, $type, a token key and an alias target; each action must be rejected or restricted to an engineering workflow. Also test whether a submitted translation can inject HTML or an unsupported placeholder into a tooltip renderer. Record the allowed schema for translation submissions and use an import validator. Preventing unauthorized edits is a more reliable control than merely instructing people to be careful.

Document the decision when translation is not enough

Occasionally a local market needs a genuinely different interaction pattern, contrast treatment or typography. The team should not conceal that design requirement inside a translation ticket. A responsible handoff says exactly what was found, why wording alone cannot fix it, which component or token is affected and what separate approval is necessary.

For example, a Mandarin description may be correct but a menu label remains clipped because the component width is fixed. Shortening the copy to the point of ambiguity is not the only option. The team can propose flexible layout, a sanctioned short label and a longer accessible name. Keep that request separate from the immutable token comparison, then retest the approved design variant. The result preserves transparent ownership: translators own meaning, designers own interaction, and engineers own data contracts.

Frequently asked questions

1. Can `$description` be an object with `en` and `zh-Hans` keys?

No. The 2025.10 format defines it as a plain JSON string. Store multi-language records in a documented companion catalog or supported extension and test every consumer. A custom object is not universally valid as a standard description.

2. Are names such as `primary` translatable?

Not automatically. A token key used in references is a technical identifier. Translate the visible title or explanation while keeping the source key unless a separately approved migration is planned.

3. Should Chinese users receive different color values?

Only through an intentional, tested design variant. Translation of $description does not authorize changing typed color components. Theme changes need separate design and accessibility approval.

4. What happens when a description translation is missing?

Follow a stated fallback policy and report the missing locale. A transparent English fallback is safer than silently labeling English copy as Chinese. Prioritize guidance related to critical states.

5. How do we check aliases after translating the guide?

Resolve the same alias graph before and after localization and compare token paths, types and values. Verify translated descriptions with a separate source-to-target review.

6. May a vendor extension hold translations?

Yes, if the project’s extension contract specifies how to store and consume them, but other tools may preserve without interpreting the data. Test interoperability rather than assuming universal display support.

Test translated wording in the actual editor at common zoom levels and with keyboard navigation. If necessary, maintain approved short and long variants outside the core format instead of truncating a safety-related exception.

8. Is a JSON schema check sufficient?

No. Parsing and structural validation cannot verify that a warning, exclusion or state name has the same meaning. The release also needs domain review and interface evidence.

9. Who owns disagreements about a token's purpose?

The design-system owner decides the intended behavior, the translator proposes accurate local language, and engineering confirms structural safety. Record the decision and its affected products.

10. How can one translation serve multiple consuming products?

Document a product-neutral role in the shared description and attach context-specific examples to product guidance. Test all important renderers, because they may use very different spaces and interaction patterns.