Repository navigation
WebMCP internationalization review checklist #273
Description
Activity
I reviewed the current editor's draft at
41d12f0,
the declarative API explainer, and the existing i18n issues. Here is my suggested disposition for all
12 top-level questions.# Suggested disposition Rationale / tracking 1 Applicable — open WebMCP defines a human-readable UI title, a natural-languagedescription, and JSON Schema annotations that can be surfaced in UI. The API carries these as unlabelled strings, with no language or base-direction metadata. The recommendation to localizetitletonavigator.languagedoes not preserve the language/direction of the resulting string or address page/site/app locale and localized alternatives. This is already tracked by #153.2 Not applicable WebMCP does not define typography, text layout, decoration, or selection UI. A user agent UI that displays a title remains subject to its platform's normal internationalized text rendering. 3 Not applicable as phrased WebMCP does not segment, concatenate, point into, or step through natural-language text. The adjacent string-length concern is already tracked: the tool namelimit is explicitly measured in ASCII code points; #219 and PR #265 address the remaining ambiguous “characters” wording, and #73 covers any future limits.4 Applicable — satisfied for the defined identifier Tool nameis syntactic, ASCII-only, and used as a map key, so matching does not require Unicode normalization or locale-sensitive case folding. It may still be worth stating editorially that names are case-sensitive, rather than leaving that to the referenced map/string semantics. Natural-language semantic matching by an agent is outside the API's string-matching processing model.5 Not applicable The specification defines no sorting of human-readable text. 6 Applicable — needs to be preserved by the declarative algorithms Declarative WebMCP uses native HTML form controls, so locale-sensitive editing UI, lang,dir,inputmode, and HTML'sdirnamemechanism are available. The schema-synthesis and execution algorithms are still TODO; they should not discard those semantics when exposing or submitting natural-language inputs. This should be included in #210's algorithm work.7 Not yet applicable to the normative draft; monitor #210 The current normative API defines no date/time data model. If declarative schema synthesis maps HTML date/time controls, it should preserve HTML's normalized submission values and the distinction that datetime-localhas no time-zone offset information; it should not infer an instant or time zone.8 Not applicable WebMCP defines Web IDL strings and JSON/HTML processing, not an alternative byte-level character encoding. 9 Applicable — open The declarative explainer puts natural-language tooldescriptionandtoolparamdescriptionvalues in HTML attributes. W3C guidance says to avoid natural-language attribute values or provide separate language/direction information. I opened #276 to track the declarative-specific design and propagation requirements.10 Not applicable WebMCP does not define formats for personal names, addresses, or other locale-structured data. Such values belong to author-defined HTML controls and input schemas. Date/time controls are covered by item 7. 11 Applicable — open title,description, and human-facing schema annotations are likely to need localization, but the API currently represents one unlabelled string per field and defines neither localized alternatives nor selection/fallback. Track the general API decision in #153 and its declarative representation in #276.12 Not applicable No normative behavior depends on culture-specific depictions, roles, gestures, or social conventions. Examples can still be reviewed editorially, but this is not an API-model dependency. Main conclusion
The primary unresolved design issue is shared by items 1, 6, 9, and 11: language and direction
information that exists at the document/element level is not represented at the tool API boundary.
This is important because W3C's guidance
requires the language and string direction of each
natural-language string to be determinable from metadata rather than heuristics.I do not think separate new issues are needed for each overlapping checklist item:
- Internationalization considerations #153 already covers the imperative API's title/description/input-schema localization and bidi
questions. - Preserve language and direction for declarative tool descriptions #276 covers the distinct declarative markup and metadata-propagation question.
- Future length limits need to define the text unit #219 / Consider restricting maximum input lengths #73 cover text units for limits.
- Define the declarative input-schema synthesis algorithm (#declarative-api is currently a TODO) #210 is the right integration point for form-control and date/time synthesis behavior.
Maintainers: please add the
i18n-trackerlabel to this checklist issue and #276 so the i18n WG sees
the review. I cannot apply repository labels with my current permissions.- Internationalization considerations #153 already covers the imperative API's title/description/input-schema localization and bidi
RESOLUTION: Initiate a11y and i18n wide reviews by our next telcon using the provided checklist responses with an understanding these reviews are an ongoing process, with further updates and refinements expected from new contributors. (issues #272 and #273)
This is a last call to provide further comments to this i18n checklist pre-work before we initiate the review.
As per the resolution, internationalization review has been requested: w3c/i18n-request#338
This issue is in response to:
TL;DR
This issue contains the internationalization (i18n) review checklist, open to review comments.
How to contribute
Review the list, suggest boxes WebMCP ticks (initially blank). For any item that has open questions, please open a new i18n-tracker issue so i18n experts are notified and can help address the issue. Please check the existing i18n-tracker issues.
Guidance from the i18n group
i18n review checklist
Note
Checked means applicable; this status reflects the group's current understanding where to focus, subject to change.