A Web of Things Thing Description translation should make a connected device understandable in another language without changing what software can read, monitor or command. In W3C WoT Thing Description 1.1, the fast, safe path is to add or review natural-language entries in titles and descriptions, preserve the identifiers and interaction forms that applications use, and test both the translated display and the original device behaviour. A bilingual device card is useful only if its labels explain the same device.
People searching for WoT Thing Description localization, multilingual smart-device metadata or Thing Description language-map QA are often facing a deceptively small job: translating “Room temperature,” “Open shade” or “Motor stopped” inside a JSON document. The words are surrounded by URLs, data schemas, actions, properties, events and protocol bindings. Translating a technical key or altering the meaning of a command could make a multilingual screen point to the wrong control, while translating only the visible sentence can leave the next user stranded in untranslated help text.
The practical answer is to separate three things before editing: human-readable language, contract identity and physical safety. Translate approved display copy; protect machine identifiers, forms and schema constraints; then verify each resulting message against a real or simulated interaction. This article shows a complete method, including a JSON example, diagnostic comparisons, failure repairs, a changed-context exercise and a release checklist. It does not claim that replacing words can validate an actual industrial device or certify a safety-critical installation.
The contract behind a friendly device name
A Thing Description, usually abbreviated TD, is a machine-readable description of a connected Thing. It tells consumers what the Thing is called, which properties can be read or written, which actions can be invoked, which events might occur, and how the corresponding communication is performed. W3C’s 1.1 Recommendation provides JSON-LD-based vocabulary and document rules. Its goal is not to prescribe how every manufacturer builds hardware; it is to describe interfaces in a way software can consume.
Imagine a school greenhouse with a temperature sensor, a ventilation fan and a remotely controlled shade. An operator interface might show “Greenhouse Shade,” “Extend shade,” and “The shade has reached the lower limit.” Teachers may want those messages in English and Chinese, while a technician wants an English diagnostic view. Those audiences need different words, yet all screens must still refer to the same shade motor, state and action endpoint. The TD provides a place to carry descriptions without inventing a new API for every language.
A software contract may use an action key such as extendShade and an HTTP form that points to https://devices.example.org/shade/actions/extend. These are not translation placeholders. One application has already been built to find extendShade; a client might sign or cache the endpoint URL. If a language editor changes either into a Chinese phrase, code looking for the old key may fail to find the action. The screen can be beautifully translated while the control becomes unusable.
The inverse mistake is to leave every human-facing title unchanged because the file is technical. A titles language map is intended precisely for different human languages. A Chinese technician should not have to understand an English-only actuator label in order to identify the intended control. The correct boundary is not “JSON must never be translated.” It is “each field must be handled according to its purpose.” That distinction is the main skill this guide teaches.
WoT 1.1 builds upon semantic web practices, including a @context declaration and terms that have defined meanings. Those terms enable a consumer to interpret the document consistently. A translation review should therefore use the W3C Recommendation as a field reference, not guess from English field names. The word action in JSON has a different status from the readable title of an action. Treating both as ordinary prose defeats the point of a structured interface description.
Three layers to mark before editing
Human-readable fields
The human-language layer includes title, description, and the multilingual maps titles and descriptions at appropriate TD locations. The singular fields are human-readable strings; the plural fields give language-tagged alternatives. A display can use these to choose wording for a locale. The values should tell a human what a property means, how an action behaves or why an event matters. Their translation is editorial work supported by device evidence.
Do not confuse grammatical translation with operational translation. “Turn on” might be appropriate for a light but misleading for a ventilation interlock that enters automatic mode rather than immediately energising a fan. Before deciding the translated imperative, determine the action’s actual effect, prerequisites and resulting state. Accurate command language cannot be obtained by translating the action identifier as if the identifier itself were an instruction manual.
Structural identity and interaction semantics
The contract layer includes keys under properties, actions, and events; the Thing identifier; @context; base; forms; href; operation declarations; protocol settings; schemas; numeric limits; readOnly; writeOnly; and enumerated machine values. These fields have functions beyond display. Changing them may change the target of a request, the type of data a consumer expects, or whether a write is permitted. A bilingual edit should not quietly become a device firmware change.
For example, a property can have a friendly name “Ambient temperature” while retaining the key ambientTemperature. It can declare a numeric type and a unit, and its form may be served by a different protocol from the control action. Translating the name is a content decision. Translating the key, replacing the unit symbol with a prose phrase inside a schema, or modifying an endpoint is a behavioural change. Reviewers should be able to prove which category each changed byte belongs to.
Physical consequences
The physical layer is what a command actually does. Some actions are harmless in a training sandbox. Others start machinery, release a lock, operate a valve or alter an alarm threshold. A technically valid JSON document is not evidence that a label is safe. If “Stop pump” is incorrectly presented as “Pause reporting,” operators may invoke the wrong control. A release gate for consequential equipment must include device-owner and domain-specialist review, not just language and schema checks.
Safety also shapes the choice of tone. Command labels should distinguish observation from execution and manual actions from automatic modes. “Read temperature” should not imply changing a setpoint. “Acknowledge alarm” should not imply silencing or resolving it if acknowledgement only records receipt. When the user faces time pressure, the cost of an ambiguous verb rises. Translation QA should therefore include an action-consequence register, not merely a bilingual glossary.
The W3C multilingual map mechanism
In TD 1.1 the plural properties titles and descriptions hold mappings from BCP 47 language tags to readable strings. They can appear at the Thing level and at interactions such as properties and actions where allowed by the model. A simple map may contain "en": "Room temperature" and "zh-Hans": "室内温度". Those entries are alternatives for the same concept, not separate device properties. The map keys describe language; the parent object identifies the Thing or interaction.
The language tag matters. en is a general English label; en-SG can mark Singapore English when a project genuinely requires that distinction. zh-Hans identifies Simplified Chinese script, while zh-Hant identifies Traditional Chinese script. Language tags must be chosen from the intended audience and not invented as marketing abbreviations. If a client requests Mandarin for a Singapore school, agree whether the copy should be in Simplified Chinese, which regional vocabulary is expected, and whether a different script is needed elsewhere.
A map may also include an @context default language declaration. The default language does not excuse mismatched or absent entries in explicit maps. A reviewer should be able to explain which text a particular consumer selects, and what happens if its requested tag is not present. Language fallback is partly application behaviour; the TD alone does not prove that every viewer implements the same user-preference cascade. Test the actual consumer rather than extrapolating from a language tag.
W3C recommends consistency of language members across MultiLanguage objects. That recommendation has a practical benefit: if the Thing title offers two languages but a critical action description offers only English, the Chinese display may contain a mixed-language safety instruction precisely where clarity matters most. A locale-coverage report can flag missing strings per interaction. But coverage alone is insufficient: two present strings might contradict one another, especially if the equipment’s firmware changed after translation.
A default singular title may remain useful for broad compatibility. Do not delete it automatically in the belief that a plural map supersedes every consumption path. Some existing consumers may render the singular form or ignore language maps. Make the compatibility decision by inspecting the supported TD version and real clients. A migration plan can preserve the original singular label while adding accurate language alternatives and measuring whether viewers use them as intended.
A small working example and its protected fields
The following compact JSON is an illustrative Thing Description fragment, not a safety certificate for a real shade. It demonstrates a TD 1.1 context, a Thing identity, bilingual titles and descriptions, one readable property, and one command. Its URLs use an example domain and are not callable production endpoints.
{
"@context": "https://www.w3.org/2022/wot/td/v1.1",
"id": "urn:example:school:greenhouse:shade:07",
"title": "Greenhouse shade",
"titles": {"en": "Greenhouse shade", "zh-Hans": "温室遮阳帘"},
"description": "Motorised shade for the west greenhouse bay.",
"descriptions": {
"en": "Motorised shade for the west greenhouse bay.",
"zh-Hans": "用于温室西侧区域的电动遮阳帘。"
},
"securityDefinitions": {"nosec_sc": {"scheme": "nosec"}},
"security": ["nosec_sc"],
"properties": {
"position": {
"type": "integer", "minimum": 0, "maximum": 100,
"readOnly": true,
"titles": {"en": "Shade position", "zh-Hans": "遮阳帘位置"},
"descriptions": {
"en": "Position as a percentage; zero means fully retracted.",
"zh-Hans": "以百分比表示的位置；零表示完全收起。"
},
"forms": [{"href": "https://devices.example.org/shade/position"}]
}
},
"actions": {
"retractShade": {
"titles": {"en": "Retract shade", "zh-Hans": "收起遮阳帘"},
"descriptions": {
"en": "Request shade retraction; motion may be blocked by a safety interlock.",
"zh-Hans": "请求收起遮阳帘；安全联锁可能阻止移动。"
},
"forms": [{"href": "https://devices.example.org/shade/retract"}]
}
}
}The example deliberately makes the machine key retractShade distinct from the displayed command “Retract shade.” In a real deployment the form’s method, operation and security scheme must match the actual protocol binding. nosec is used only to keep the classroom fragment readable; it must not be copied into a production system as a recommendation to remove authentication. The lesson is the border between localized language and interaction identity, not authentication design.
The percentage note is more important than it looks. A translator might assume zero means the shade is fully extended because that is how another manufacturer’s panel displays position. The example explicitly defines zero as fully retracted. The translated description must preserve that convention even if it feels counterintuitive. If a multilingual dashboard shows the opposite interpretation, a technician may believe the motor is stuck or repeatedly send an unnecessary command.
The phrase “may be blocked by a safety interlock” also needs exact handling. It does not promise that the command will execute, and it does not assert that a fault has occurred. Removing the qualifier would misrepresent device behaviour; changing “may” to “will” would be a different mistake. A human translation must preserve operational modality, which is often hidden inside small words. The Chinese rendering should communicate a possible prevention of movement without implying that the safety mechanism has been bypassed.
In this fragment the securityDefinitions and security fields are machine configuration, not content to translate. A reviewer may raise a separate finding that an example-only unauthenticated scheme is unsuitable in deployment, but should not quietly alter it as part of translation. Keeping scopes separate makes both reviews more auditable. A localization release can be blocked for security without disguising that judgement as a language edit.
How to translate the document quickly without touching the wrong bytes
First, freeze a known-good source
Capture the TD version, source hash, target device build, test environment and consumer application versions. Record whether the source document represents live firmware or a draft interface. A translation that is perfect for an old device revision may be wrong for a new motor whose command semantics changed. The source snapshot becomes the reference against which all later diffs are checked. Without it, a reviewer cannot tell whether a changed limit was introduced by firmware engineering or by a localization accident.
Make a structural inventory of paths where human strings appear. Typical entries include a Thing title, descriptions for a status property, action instructions, event explanations and optional schema descriptions. Link each location to a device-screen context or an interaction test. It is much faster to translate a controlled list of passages than to give a general machine translator an entire JSON file and then inspect hundreds of keys that should never have moved.
Second, design an exact extraction contract
Extract only approved text values from permitted paths, and retain a stable pointer to each location. For instance, /actions/retractShade/descriptions/en identifies a human description, while /actions/retractShade/forms/0/href is protected. Keep placeholders, parameter names, numeric values, unit strings and action references in a separate protection register. The extraction contract is a technical specification for the translation work, not a linguistic suggestion.
Beware of simple pattern matching. A regular expression searching for the word title may miss nested language maps or capture an unrelated object. A JSON parser can navigate structural paths and distinguish a text value from a key. In a production workflow, document the extraction code or localization system mapping, then test it on a small fixture containing nested descriptions, absent maps and unusual characters. If the extractor itself is unreliable, a translation memory only spreads the error faster.
Third, resolve what the device does
Ask the product owner for a control-state diagram, user-interface screenshots, a safe simulator and any operating manual that defines terminology. An action named reset might reset a counter, clear a fault latch or reboot a controller. Those are not interchangeable. The translator should not choose a target-language verb from the identifier alone. Write a short source-side intent statement for every ambiguous phrase, including the expected consequence and any preconditions.
For numeric property descriptions, request the unit, allowed range and physical reference point. “Level” may mean liquid depth, battery charge, fill percentage or an alarm class. “Open” may describe a contact state or an instruction to open a door. Precise terminology makes translations reusable; vague glossary entries create recurring research. The fastest long-term method is to store approved term plus context, prohibited alternatives and an explanation of the physical object.
Fourth, translate language values, not JSON structure
Preserve the original keys and add the target language member inside the relevant map. Do not replace positions, forms, input, output or properties with localized words. Do not turn a numeric enum into translated string values unless the application contract explicitly defines a different schema; ordinary localization should provide display names in an approved presentation layer. A changed API value can break automations even when a human operator approves its wording.
If the target language lacks a short equivalent for a hardware term, prioritize precision over artificial brevity. A longer title may be necessary, but it can be accompanied by a concise approved interface label and a fuller description. Do not invent abbreviations solely to fit a narrow mobile card without testing comprehension. Shortness is a layout constraint; it cannot justify a false claim about what a device will do.
Fifth, compare structurally before visual review
Parse the source and target JSON, normalize only formatting differences, and produce an allowlisted semantic diff. Keys outside the human-language paths should match byte-for-byte or through a carefully documented equivalence check. Differences in id, href, op declarations, numeric bounds, readOnly, writeOnly, input schema, output schema or security settings are release blockers. A clean text diff is not enough; reformatting JSON may hide a changed value among harmless whitespace differences.
Check language tags against the agreed locale inventory. Reject mistyped tags such as a project-specific nickname that looks plausible to a human but cannot be interpreted by consumers. Also test JSON escaping, Unicode characters and serialization round trips. Smart quotation marks inside a value are ordinary content, but an unescaped quotation mark can break parsing. Valid UTF-8 does not automatically mean acceptable display; verify fonts and rendering for the intended scripts.
Sixth, test actual consumption paths
Load the localized TD in every supported viewer, not just a generic JSON parser. Select each supported language, revisit the Thing overview, examine each property, inspect each action detail, and trigger only safe simulator operations. Confirm that the screen presents the correct description next to the correct control and that the request generated by the viewer still targets the original operation. The test should observe both text and behaviour because a consumer may implement locale fallback incorrectly even when the TD is correct.
Record the evidence as a small table of locale, interface path, expected text, observed text, operation path and result. For a read-only property, verify that the viewer did not render it as editable. For an action whose execution can be blocked, verify the interface does not promise immediate success. Repeat the test on a narrow screen and with assistive technology where those consumers are supported. A language-complete map can still produce an unusable interface if controls are clipped or focus order becomes confusing.
Ten diagnostic checks that catch costly mistakes
Identity drift and URI drift
Compare the root id and all interaction form URLs to the frozen source. If either changed, stop. Replacing an identifier with a translated phrase creates a new apparent Thing identity, while translating the URL can make software send a request to an address that does not exist. The repair is to restore exact identity, extract its human label into titles, and retest the unchanged form. Even a harmless-looking added suffix can invalidate caches or digital references.
Missing language coverage
Count expected language tags at each important readable location. Missing translations need an explicit fallback policy rather than silent acceptance. A useful severity rule is that omitted aesthetic descriptions are warnings, whereas missing action or hazard explanations are blockers when that language is offered to operators. Repair means translating the missing meaning or withholding the affected locale until the user experience is coherent. A partially translated control panel can be worse than one clearly labelled as English-only.
Conflicting commands
Look for translated imperatives that reverse, soften or exaggerate an action. Extend and retract, start and stop, arm and disarm, enable and disable must remain distinguishable. If two different keys become the same short target label, inspect their outcomes and add specificity. A glossary cannot settle this alone; test a realistic scenario in which a user is choosing between both controls. The translation passes when a target-language user can predict which command is selected without relying on the English key.
Lost qualifications
Search for modal words, conditions and negation in safety-related source prose. “May stop automatically,” “cannot operate while the cover is open,” and “only if authorized” express different constraints. Machine translation often produces fluent outputs that omit a qualifier. The repair is to compare the target against a source-side truth table: whether operation is permitted, required, optional, temporary or impossible under each condition. This is semantic QA, not a keyword match, because languages encode modality differently.
Unit and range confusion
Keep numeric machine fields intact while checking the wording that explains them. A range of zero to one hundred might represent percentage, scaled actuator position or a normalized signal; it is not automatically degrees. The translation must preserve which endpoint means fully open and which means fully closed. If a display localizes a decimal separator, ensure that the actual protocol value remains machine-readable in its required format. Locale formatting belongs in presentation unless the protocol explicitly specifies otherwise.
Event descriptions and time
Events can be named with a past-tense appearance while actually referring to a notification stream. “Motor jammed” may mean the condition has just been detected or is currently active. Ask whether the event includes a timestamp, severity, persistence model and acknowledgement state. Translate the description so a reader knows whether action is required now or whether this is historical information. Never translate an event identifier in a way that changes subscriptions, filters or historical log queries.
Language fallback surprises
Request a locale that is not present, then test a nearby variant and a completely unrelated language. Does zh-SG fall back to zh-Hans, to an agreed default, or to a blank field? Different consumers may behave differently. The desired fallback must be documented at the application level and tested rather than assumed from the recommendation alone. Repair may involve adding the required language map members or improving the viewer’s locale-resolution logic; do not modify device command semantics to solve a display problem.
Accessibility and speech
A label can look fine on a dashboard yet be confusing when spoken by a screen reader. Acronyms, punctuation, abbreviations and mixed scripts require attention. Give action buttons informative names that express effect, not just “Go” or “OK.” Inspect whether repeated labels are differentiated by context; two buttons called “Reset” may be impossible to distinguish when focus moves away from their panels. Translation review should include spoken output and keyboard flow when the interface supports those interactions.
Security text versus security behaviour
Warnings such as “Credentials required” or “Connection not secure” may be human-readable, but protocol authentication and security definitions are not translation targets. If the target translation says that authentication is optional while the TD demands it, the wording is wrong; if the translation pipeline removes the security declaration, the artefact has changed function. Separate the language ticket from the security ticket, block deployment as appropriate, and preserve both incident records. Do not let a green language score imply that security controls are satisfactory.
JSON validity versus operational truth
Passing a JSON parser and even a TD validator is necessary but insufficient. A perfectly conforming description can refer to obsolete firmware, outdated equipment or a dangerous misunderstanding. Pair structural checks with simulation, device-owner signoff and user comprehension testing. If a command is impossible to test safely, mark it unverified and hold release rather than claiming it works. A system should distinguish syntactic correctness, specification conformance, linguistic accuracy and observed behaviour as separate results.
Real-world adaptations and decisions
Classroom climate-monitoring demonstration
A teacher may want students to read temperature trends in two languages without operating machinery. Publish a read-only, simulated TD and keep its controls clearly disabled or absent. Translate the property label and its explanation, including sampling interval and unit. The goal is comprehension of the same measurement rather than device control. In this case the review can focus on bilingual scientific terminology and charts, while still checking that the property key and data type remain stable.
Public library environmental sensor
A library might display air quality to visitors speaking several languages. “Good air” is too vague without the actual metric or classification rule. A TD can describe a particulate sensor while a separate public interface applies local health guidance and accessibility requirements. Translators should not write a medical assurance that the technical source never made. The release should make clear which values come from the sensor, which interpretations come from a public authority, and which words merely help readers navigate the interface.
Smart home heating system
“Set target temperature” may refer to a thermostat setting rather than the measured room temperature. If both properties use “Temperature” in the target language, residents can mistake one for the other. Distinguish current reading, target setpoint and operating mode explicitly. Check whether the device itself enforces bounds and whether the UI rounds displayed values. Translation does not authorize changing setpoint constraints or converting units in a way that corrupts requests.
Agricultural irrigation equipment
Irrigation controllers often distinguish a manual run from an automatically scheduled cycle. A verb like “Start” is incomplete without a mode and duration. Translate the action description from operating evidence, not assumptions about a generic water pump. Verify that a local farmer can distinguish immediate activation, scheduling and override. If regional terminology differs, record the approved term for the deployed market rather than forcing a universal translation into every language variant.
Laboratory automation
A laboratory may label a robotic chamber status and provide bilingual help for researchers. State changes can affect samples, contamination protocols and equipment availability. Translators should ask whether a command physically moves a mechanism or only queues a task. Keep data and safety interlock declarations unaltered, test in simulation, and require lab-owner approval where action labels are consequential. The more specialized the physical process, the less reliable a general translation memory becomes without context.
Museum demonstration exhibit
An interactive exhibit might use a WoT TD for physical buttons and displays. Visitors need approachable labels, but a museum curator may deliberately simplify language for children. Simplification is allowed only if it preserves the action’s practical result. “Make the fan go” might be acceptable for a toy model but not for a ventilation safety control. Use two layers if necessary: a short visitor label and a more precise technical description, each reviewed for the intended audience.
Shared devices across multiple schools
A district deployment may reuse one device model in different schools. Avoid translating each school-specific screen independently because inconsistent action names will confuse staff who move between sites. Store terms at model or product level and document local exceptions. At the same time, do not assume all installations have identical hardware or firmware. Include configuration fingerprints so that a correct localization file is applied only to compatible devices.
Offline and intermittently connected interfaces
A cached TD may outlive the physical device’s current software. Bilingual labels could then describe an action that no longer exists. A robust client should record TD version or retrieval time and handle stale data. Translators cannot solve cache invalidation with words, but can help by flagging source version dependencies during localization handoff. Test what happens when the consumer loses connectivity: a button should not suggest guaranteed execution when the network cannot confirm a command.
Mixed human and machine terminology
Some device labels contain product codes, model numbers or acronyms. Keep an identifier unchanged if it is the recognizable asset ID or a service key, but explain it in the description where useful. Do not translate model names into a phrase that could be confused with another product. A bilingual glossary should distinguish protected names, ordinary terminology, and units. This lets translators move quickly without making every unfamiliar token a separate guess.
Changing device ownership or vendor
When a school replaces a fan controller with another brand, apparently similar commands can differ. Retiring one TD and publishing another is an integration decision. Do not copy translations wholesale across the devices simply because their action keys look alike. Compare effects, preconditions, units, permitted operations and failure states. Translation memories can suggest candidate sentences, but each needs renewed approval against the new device contract.
An efficient review workflow that remains auditable
Start with a requirements sheet naming source language, target tags, intended consumers, hardware model, firmware version, expected fallback and consequence level. The sheet prevents questions being answered differently in email and in the translation editor. Attach a glossary with approved terms and a protected-field inventory. Where no domain expert is available, limit the draft to low-risk display material and flag unresolved operational claims rather than inventing answers.
A translator can work in batches by interaction family: Thing overview, read-only properties, writable properties, actions and events. Each family has recurring grammar and terminology. This is faster than random ordering because decisions about tense, units and action naming remain visible. Once a family is complete, a second reviewer checks consistency with the frozen source and the product manual. If the source is ambiguous, record the question at the exact JSON path.
Use a layered QA report. Syntax checks answer whether JSON is parseable. Schema checks answer whether the TD follows the supported formal structure. Whitelist checks answer whether forbidden fields changed. Linguistic review answers whether the message is accurate in the target language. Behaviour testing answers whether the displayed control still invokes the intended operation. A release must not merge these into one meaningless “pass” mark, because a failure in any layer requires a different repair owner.
For change management, compare hashes of the original contract fields rather than trusting memory. A new source build may have additional actions and changed descriptions while keeping most fields identical. Such changes should generate a targeted retranslation job. By contrast, a mere punctuation correction in the English title should not automatically cause a firmware regression cycle. Classify change type and risk so that effort follows consequences, not file size.
When an issue is fixed, rerun the smallest test that diagnoses it and then repeat the relevant release suite. A changed map entry needs locale rendering and coverage checks; a restored identifier also needs structural integrity checks. Keep evidence of the old and new text, the issue’s cause and who approved the repair. This is how a fast translation process gains reliability rather than becoming a sequence of rushed untraceable edits.
Changed-context transfer exercise: from shade to freezer
Consider a school laboratory freezer described by a TD. The original English property is called “Door state,” with machine values OPEN and CLOSED. The source description says “Read-only contact state; OPEN means the door switch is not engaged.” A new locale editor proposes changing the property key to a translated phrase and localizing the machine values to natural-language equivalents. The editor also translates the singular title while forgetting the titles map. What should be approved, what should be rejected and what must be tested?
The appropriate repair is to preserve the property key, the enum tokens and the read-only declaration exactly. Add translated display strings at supported human-language locations; if the consumer needs friendly renderings for enum values, provide an explicitly designed presentation mapping outside the machine enum contract. The description must preserve the switch interpretation and not claim that an open switch necessarily proves the physical door is fully open. That nuance matters because an electrical contact and a mechanical position are related but not identical observations.
The test should parse and validate the TD, compare protected fields, load the intended locale, display the property and confirm the true state in a safe simulator. It should include a deliberately disconnected switch case if available and an unsupported locale fallback. The freezer case differs from the greenhouse because an incorrect door-state interpretation may threaten samples; a competent review therefore involves laboratory staff and a more stringent release gate. The method transfers, but the consequence assessment changes.
Practical pre-release review checklist
Check the source identity and scope first: exact TD version, device identity, firmware, consumer, locale inventory, source snapshot and owner. Review the allowed text paths against the translator’s actual diff. Verify that every language-tagged entry belongs to the intended concept, that no identifier or endpoint has moved, and that fallback decisions are written down rather than left to chance. Confirm that the glossary resolves ambiguous terms about operating modes and state transitions.
Then inspect the behaviour and people layer: do target-language users understand what each control will do, and do simulated operations match that understanding? Are conditions and limitations preserved? Are units and numeric meanings explained consistently? Are accessibility, small-screen rendering and mixed-language cases acceptable? Can a reviewer identify every untested action, and has an appropriate specialist signed off where physical safety is affected? The right answer to an unverified critical item is not automatic approval.
Finally preserve a small release packet: source and target hashes, relevant standards versions, localization diff, syntax and schema results, locale screenshots, test observations, reviewer names, open defects and rollback instruction. The point is not paperwork for its own sake. It is being able to tell a future technician whether a strange label came from a translation choice, an old source document, a faulty consumer or a hardware change. Good evidence reduces investigation time after deployment.
Limits and conclusion
A Thing Description is not a universal device safety standard, and this article is not a substitute for a manufacturer manual, a device-ownership review or testing under relevant local requirements. Consumers differ in their support for language maps and fallback. TD validation does not establish that an actuator moves safely or that an operator interprets a warning correctly. Where life, health or property depends on a command, specialized engineering and operational assessment are necessary.
Still, a good multilingual TD can make connected technology much more usable. It lets a school, laboratory or public service carry human explanations beside a stable machine interface. Translators become faster when they know precisely which text is theirs to change and precisely what evidence they must keep unchanged. The method is straightforward: freeze the contract, translate supported language maps, protect machine identity, test the real consumer and keep a repair trail.
The deeper principle is that translation should move understanding without silently moving control. When a reader sees a familiar-language label, they should receive the same truthful model of the device that the source-language reader receives. That is more useful than either word-for-word translation or an attractive dashboard whose buttons no longer mean what they say.
Frequently asked questions
Can I translate the JSON keys under `actions`?
Not in an ordinary localization pass. Those names identify actions for consumers. Keep them stable and translate human labels in the supported fields.
Why are `titles` and `descriptions` plural?
They are language maps holding multiple translations for the same Thing or interaction. The singular fields represent individual strings and may be kept for compatibility.
Does a `zh-Hans` entry automatically satisfy every Chinese-speaking audience?
No. Script and regional terminology are separate choices. Specify the audience and review the actual wording for that audience.
What happens if a consumer does not support a language map?
It may show a singular title, another fallback or no translation. Test the intended consumer; do not assume all viewers behave alike.
Can an AI translator process the entire TD file?
It can assist with selected extracted text, but the integration should prevent edits to identifiers, schemas and endpoints and require human review for consequential wording.
Why does a valid TD still need a behaviour test?
Validation checks document rules. It cannot prove a physical command is safe or that the label describes current firmware accurately.
Are units translated like ordinary words?
Readable explanations can be localized. Protocol-level units, numeric values and schema constraints must follow their technical definitions, not language preferences.
Is an English-only emergency message acceptable in a bilingual interface?
That is a product safety and accessibility decision requiring explicit risk review. Do not silently classify critical missing text as a harmless cosmetic issue.
Can I reuse a previous translation after a firmware update?
Only after checking whether each underlying property, action and event still has the same meaning and consequences. Identical labels do not guarantee identical behaviour.
What is the fastest first test for a new locale?
Parse the JSON, compare protected fields, check map coverage and load the locale in the actual viewer. Follow with safe end-to-end interaction tests.
Authoritative sources
- W3C, Web of Things (WoT) Thing Description 1.1, Recommendation.
- W3C, WoT Architecture 1.1.
- IETF, BCP 47 language tags, RFC 5646.
- W3C, JSON-LD 1.1 Recommendation.