Internationalization Self-Review Questionnaire for VC Rendering Methods v1.0

Internationalization (i18n) Self-Review of Verifiable Credential Rendering Methods v1.0

This short review is for the following spec: Verifiable Credential Rendering Methods v1.0.

The specification defines an extension mechanism for the Verifiable Credential Data Model with which an issuer associates render templates with a verifiable credential, so a holder or verifier can present it through a visual, auditory, or (in the future) haptic medium. Because its subject is presentation rather than data alone, more of the questions below apply than would for a pure data model. It defines three render suites: card (a declarative JSON template producing standardized structured output), html (an issuer-supplied HTML/CSS/JavaScript fragment executed in a sandboxed iframe), and nfc (a static binary payload).

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.

   The specification carries natural language text in several places, with inconsistent language and direction support that we'd like i18n's feedback on. We tried to rely as much on the html render method as possible to handle complex i18n concerns. For the card render method, we found ourselves having to effectively re-create minimal features that would enable i18n.

   What is supported: Each entry in the card render suite's fields list has an OPTIONAL language property carrying a BCP 47 tag and an OPTIONAL direction property carrying a base direction as specified in String Metadata, each indicating the language and direction of that field's label and/or value. This appears in both the card template schema and the card output schema, so we think we're covered there.

   There are three places that carry human-readable text with no language or direction metadata:

   • The card suite's top-level name and description are plain strings. A card's most prominent text is therefore the text with the least metadata. Should we just specify a card as having a language and be done with it? Or should we try to make it so different languages/directions can apply to each value separately (so you can mix/match within one card template)? It feels easier to do the former.
   • A render method's own name and description, described in the specification as a hint displayed in a graphical interface that lets a person choose between presentation modes, are plain strings. The solution here could be the same as the item above.
   • The html render suite has no language declaration mechanism at all -- should we specify a language at the top-level of the template (same "simple" solution as for the card one?).

We would welcome i18n's advice here, whether the render method should carry a language/direction declaration at the top-level, or at the per-field level.

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.

   This specification does not define typographic behavior itself, but the html render suite deliberately hands typographic control to the issuer: the template is an HTML fragment carrying its own CSS, so line-breaking, justification, emphasis, font selection, and text decoration are whatever the template author writes, interpreted by the rendering environment's own text layout. We think this is fine because we're just "using HTML", which has had thorough i18n review.

   The card render suite deliberately avoids this: it produces a structured output that the consuming wallet renders using its own UI and its own typography, so a wallet's existing internationalization applies... but that might not be great because wallet vendors might not know much about a11y. Is there something we should point them to/warn them about?

   The outputPreference.style object lets an issuer state a preferred width and height for the iframe. Fixed dimensions chosen against one language's text length may clip or overflow when the same template renders longer translated strings. We don't really know how to remedy this -- has a11y come across this before?

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.

   The specification defines no text pointing, fragmentation, concatenation, selection, or stepping. Values resolved from a credential by JSON Pointer are substituted whole, and the specification states explicitly that compound data across multiple fields is not supported and each field references a single JSON Pointer, so no string concatenation is defined. Any text selection within a rendering is behavior of the rendering environment.

   • 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.

   • 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.

   The specification defines no sorting.

   • 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.

   No render suite defines an input mechanism, and the specification defines no input method. Because the html suite executes template JavaScript, a template could create input controls, but that is outside anything the specification describes or constrains. We know of no way to limit that behavior, should we if there is a mechanism? We don't want to cut off innovation w/ render displays.

   • 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.

   The card render suite carries validFrom and validUntil in both its template and output schemas, described as XMLDateTime strings and typically resolved by JSON Pointer from the credential's own validFrom/validUntil, which follow the Validity Period model of the Verifiable Credentials Data Model and carry an unambiguous absolute point in time with a timezone offset. Field values resolved from the credential may likewise be dates.

   Two considerations for reviewers. First, the card suite passes these values through as strings; the specification does not say whether the wallet is expected to localize them for display, or to show the ISO value as-is, so an implementation may reasonably do either and the same card renders differently across wallets. Second, the specification does not address non-Gregorian calendar systems, whether for display of a Gregorian absolute timestamp in a locale that uses another calendar, or for a credential whose claims carry a date already expressed in one. We think this is fine since it's just following guidance i18n provided for the VC Data Model v1.0 and v2.0 specifications.

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.

   The specification defines no alternative character encoding.

   • 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.

   The html render suite defines markup structure directly, but there is no way to pass in locale information from the runtime environment. Should we add that? Or do iframe's do that automatically from the runtime environment? IOW, should we pass in the locale from the runtime environment into the sandboxed environment?

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.

    The specification does not define names or addresses as data; it defines a presentation mechanism through which a credential's names, addresses, and dates are displayed, so the flexibility question falls on how presentation is structured rather than on the field definitions.

    The card suite's model is a flat, ordered list of label/value pairs plus a fixed set of top-level properties. That structure imposes no name ordering or address structure of its own, which is good, but it also means each field is a single JSON Pointer to a single value: the specification states explicitly that compound data across multiple fields is not supported. A credential whose name or address is structured as multiple components therefore cannot be composed into one culturally appropriate display string by a card template; each component becomes its own field, in the order the template author chose. Reviewers may wish to consider whether that constraint prevents culturally appropriate rendering of structured names and addresses in the card suite.

    The html suite has no such constraint, since template code can compose values freely, and the specification's stated rationale for preferring an executable template over placeholder substitution includes exactly this class of formatting need.

    Dates are handled as described in item 7 (we try to just follow the guidance on dates provided by i18n review for the VC Data Model).

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.

    The specification defines no language or locale property on a render method, so there is no machine-readable way to say this render method is the French one. outputPreference carries accessMode, mediaType, and style, but no language. Consequently there is also no defined selection algorithm by which an application picks the render method matching a user's language preferences; the only aid is the human-readable name, which is itself untagged. That's likely not good, but we don't know if per-language templates are the way to go and would love to hear back from i18n on this issue.

    Within a single render method, the card suite's per-field language labels a field's text but provides no way to supply the same field in several languages and let the consumer choose; fields is a flat list, so multilingual alternatives would appear as duplicate fields. This "bug" makes us think that we should have per-language templates, otherwise it seems like we might create yet another i18n templating mechanism.

    Localized images are also unaddressed. The card suite's icon is a single URL or data URI with no locale alternatives, so an ecosystem needing a locale-specific logo or a wordmark rendered in the local script has no defined way to express it. This also points toward per-language templates.

    We would welcome i18n's guidance on whether a language property on renderMethod and a defined selection algorithm should be added.

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).

    The specification defines no culturally specific depictions, gestures, or norms of its own, and neither the card schema nor the render method vocabulary presumes any.

    • Not applicable

Start with the linked Verifiable Credential Rendering Methods v1.0 specification and compare the card and html render-suite sections with the i18n self-review questions. Review the language, direction, typography, date, markup, and localization concerns raised in the issue; done requires recorded guidance or agreed specification changes, but the issue does not identify files or tests.