Short i18n review for WebGPU / WGSL

[Kangz]

Short i18n review checklist is here

This review is for both WebGPU and WGSL since WGSL is a companion language to the WebGPU API.

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

   The WebGPU API contains several DOMString that are reasonably expected to be surfaced to a human:

• GPUCompilationMessage.message which is a compiler message from the WGSL compiler.

• GPUDeviceLostInfo.message that may describe in human-readable language the reason why the GPU was lost (it was disconnect, timed out, etc).

• GPUValidationError.message which describe in human-readable language what error happened (similarly to DOMException.message, see the explainer for why it is different)

• GPUCompilationMessage points at a location in a user-provided string by line number, position on the line, string offset, and length.

• The WebGPU adapter identifier, depending on the resolution surrounding the GPU Adapter Identifier discussions. The information surfaced to the user may contain the GPU's vendor name, chip name, or other information.

  The expectation is to use "first-strong" augmented with Unicode markers if need be. The implementations will have to decide when to add the markers.

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.

   N/A WebGPU/WGSL doesn't allow producing text (unless Javascript uses WebGPU to draw text, but that's not decidable at the WebGPU level)

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.

   N/A WebGPU/WGSL doesn't allow working with text.

4. If the spec (or its implementation) allows searching or matching of text, including syntax and identifiers

   WebGPU has an associated shading language, WGSL. WGSL allows any Unicode in comments and UAX31 XID_Start and XID_Continue in identifiers. Identifiers in the WGSL store and compare by their code points and not through UAX15 equivalences such as canonical or compatibility. But where relevant, including places within WebGPU API, user agents are strongly encouraged to display a developer-visible warning when there are non-reader-visible code point differences, such as non-normalized code point sequences.
   WGSL and WGSL identifiers are relevant inside parsing of WGSL, as well as in the WebGPU API GPUShaderModuleDescriptor.code/sourceMap/hints and GPUProgrammableStage.entryPoint/constants members.

5. If the spec (or its implementation) sorts text

   N/A WebGPU doesn't sort text.

6. If the spec (or its implementation) captures user input

   N/A WebGPU doesn't capture user input.

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

   N/A WebGPU only deals with time in the timestamp queries, and they return nanosecond timestamps that are not related to any particular origin (it may be Unix epoch, or since the computer was booted, or the GPU booted, or anything else).

8. If the spec (or its implementation) allows any character encoding other than UTF-8.

   WGSL source code is specified in GPUShaderModuleDescriptor.code as USVString. WGSL uses UTF-8 encoding and only disallows the null character. Comments can contain any Unicode character, and identifiers can contain XID_Start or _ low line at first character and XID_Continue for the rest from UAX31, which is the Unicode recommendation for Identifiers.

   All other strings (labels, debug group names, entry point names, etc) are developer-defined strings.

9. If the spec (or its implementation) defines markup.

   N/A WebGPU doesn't define markup.

10. If the spec (or its implementation) deals with names, addresses, time & date formats, etc

    N/A WebGPU doesn't deal with such information.

11. If the spec (or its implementation) describes a format or data that is likely to need localization.

    N/A WebGPU doesn't define a format other than WGSL.

12. If the spec (or its implementation) makes any reference to or relies on any cultural norms

    N/A WebGPU doesn't reference cultural norms (as far as we know).

[Kangz]

Spec editors @kvark @kainino0x @toji @dneto0 @litherum PTAL! @kdashg PTAL too! This is part of the process of asking for an internationalization review for a specification. Feel free to edit the first comment with more info if needed. Once we're happy with the result we can add the i18n-tracker label to start the i18n review.

[kainino0x]

Maybe briefly mention that object labels, debug group/marker names, WGSL code/entryPoint/hints/constants are all developer-defined strings. Just to avoid ambiguity. Otherwise LGTM!

[kdashg]

Looks good, thanks for heading this up!

[toji]

You'll probably also want to mention that GPUCompilationMessage points at a location in a User-provided string by line number, position on the line, string offset, and length. This feels like the following list item but in reverse, so not sure if actually falls under that group.

If the spec (or its implementation) allows the user to point into text...

[Kangz]

Probably worth mentioning, please edit the top comment!

[toji]

Done.

[mehmetoguzderin]

It might help to update this because #1160 (comment) is getting in the API and WGSL.

[kainino0x]

Added above.

[mehmetoguzderin]

It seems like the specifications might receive feedback due to the lack of presence of directionality and language information in natural language messages. So, in anticipation, here is a quick web specs recap of the situation with regards to the advancement of localization of these strings:

Despite the ongoing discussion (see w3ctag/design-reviews#716 thread), WebIDL has no primary, tailor-cut interface for this for the time being.

There already are a few specs that resolve this through appending "lang" (stands for @language in JSON-LD) and "dir" (stands for @direction in JSON-LD) fields.

WebIDLpedia is helpful for anybody looking to look up: https://dontcallmedom.github.io/webidlpedia/members.html

The following text is a copy of w3ctag/design-reviews#716 (comment) comment by @aphillips as of posting, which I think is a helpful summary.

I18N has been requesting metadata for some time and there are different dispositions depending on the specification and its needs. There are 18 specifications in the list below. Separately I am reviewing specs that preceded our efforts in this area as well as the list of potential new specifications.

First, JSON-LD added features to the specification allowing document and item level metadata.

The following specifications either added support using JSON-LD or are in the process of doing so:

• WOT Thing Description
• pub-manifest
• activity-pub
• web-annotation

Some specifications added locally defined metadata (i.e. their own language and direction fields in natural language values and which are similar to the Localizable type described elsewhere in this request):

• appmanifest
• miniapp-manifest
• TTML
• activitystreams (based on WebAppManifest)

One specification (WebAuthn) defined its own serialization scheme; we are still working with them on the details of that scheme.

The following specs are in one way or another waiting on this discussion or have proceeded:

• secure-payment-confirmation
• payment-request
• vocab-duv
• mediacapture
• web-share
• micro-pub
• SHACL

SHACL probably should have adopted the JSON-LD approach. micro-pub entangles metadata with the question of localizable error messages and so might not apply.

[Kangz]

Closing this issue, I18n WG filed a bunch of feedback so we can continue the work in the individual issues.