WebMCP internationalization review checklist

[anssiko]

This issue is in response to:

RESOLUTION: Initiate wide review of WebMCP with the i18n and a11y groups along with collateral materials.

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

The primary purpose for this page is educational. It helps you to learn about internationalization features that may affect the design of your spec. You should read it and Internationalization Best Practices for Spec Developers as early as possible, so that you are aware of what your spec will need to address. Then, to ensure that you haven't missed anything, you can also use this page as a checklist prior to publishing the spec as a FPWD.

You should raise an issue in your own repository to show the answers to these questions, and attach the i18n-tracker label so that we are notified. Under 'Create a Report' you'll find a way to create a report.

i18n review checklist

1. If the spec (or its implementation) contains any natural language text that will be read by a human (this includes error messages or other UI text, JSON strings, etc, etc), ensure that there’s metadata about and support for basic things such as language and text direction. Also check the detailed guidance for Language and Text direction.

   Comments_go_here.

   • Not applicable

2. If the spec (or its implementation) allows content authors to produce typographically appealing text, either in its own right, or in association with graphics. take into account the different typographic styles used around the world (for things such as line-breaking, text justification, emphasis or other text decorations, text selection and units, etc.) Also check the detailed guidance for Typographic support.

   Comments_go_here.

   • Not applicable

3. If the spec (or its implementation) allows the user to point into text, creates text fragments, concatenates text, allows the user to select or step through text (using a cursor or other methods), etc. make allowances for the ways different scripts handle units of text. Also check the detailed guidance for Text-processing.

   Comments_go_here.

   • Not applicable

4. If the spec (or its implementation) allows searching or matching of text, including syntax and identifiers understand the implications of normalisation, case folding, etc. Also check the detailed guidance for Text-processing.

   Comments_go_here

   • Not applicable

5. If the spec (or its implementation) sorts text ensure that it does so in locally relevant ways. Also check the detailed guidance for Text-processing.

   Comments go here.

   • Not applicable

6. If the spec (or its implementation) captures user input ensure that it also captures metadata about language and text direction, and that it accommodates locale-specific input methods.

   Comments go here.

   • Not applicable

7. If the spec (or its implementation) deals with time in any way that will be read by humans and/or crosses time zone boundaries ensure that it will represent time as expected in locales around the world, and manage the relationship between local and global/absolute time. Also check the detailed guidance for Local dates, times and formats.

   Comments go here.

   • Not applicable

8. If the spec (or its implementation) allows any character encoding other than UTF-8. make sure you have a convincing argument as to why, and then ensure that the character encoding model is correct. Also check the detailed guidance for Characters.

   Comments go here.

   • Not applicable

9. If the spec (or its implementation) defines markup ensure support for internationalization features and avoid putting human-readable text in attribute values or plain-text elements. Also check the detailed guidance for Markup & syntax.

   Comments go here.

   • Not applicable

10. If the spec (or its implementation) deals with names, addresses, time & date formats, etc ensure that the model is flexible enough to cope with wide variations in format, levels of data, etc. Also check the detailed guidance for Local dates, times and formats.

    Comments go here.

    • Not applicable

11. If the spec (or its implementation) describes a format or data that is likely to need localization. ensure that there’s an approach in place which allows effective storage and labelling of, and access to localised alternatives for strings, text, images, etc.

    Comments go here.

    • Not applicable

12. If the spec (or its implementation) makes any reference to or relies on any cultural norms ensure that it can be adapted to suit different cultural norms around the world (ranging from depictions of people or gestures, to expectations about gender roles, to approaches to work and life, etc).

    Comments go here.

    • Not applicable

[mlmrx]

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-language description, 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 localize title to navigator.language does 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 name limit 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 name is 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's dirname mechanism 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-local has 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 tooldescription and toolparamdescription values 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-tracker label to this checklist issue and #276 so the i18n WG sees
the review. I cannot apply repository labels with my current permissions.