Mismatch with MUST clause and examples in default language section

[himorin]

In section 8. Default Language,

One Map contained in an @context Array MUST contain a name-value pair that defines the default language for the Thing Description, where the name is the Term @language and the value is a well-formed language tag as defined by [BCP47] (e.g., en, de-AT, gsw-CH, zh-Hans, zh-Hant-HK, sl-nedis).

1. This section has MUST clause to include default language in @context array, but examples in this spec (e.g. example 1, example 2, example 4) do not have such.
2. In 6.3.2 Human-Readable Metadata in WoT Things Description, handling of language is discussed in detail and fallback is also defined (like quoted below). This section seems not to be consisted with these.

When metadata such as @direction is not present, TD Consumers SHOULD use first-strong detection as a fallback. For the MultiLanguage Map, TD Consumers MAY infer the base direction from the language tag of the individual strings.

Also, there should be some mention about which language should be applied for reply of property request, write property, or action in protocol bindings.

[benfrancis]

Thanks for reporting this issue, @himorin.

• This section has MUST clause to include default language in @context array, but examples in this spec (e.g. example 1, example 2, example 4) do not have such.

• In 6.3.2 Human-Readable Metadata in WoT Things Description, handling of language is discussed in detail and fallback is also defined (like quoted below). This section seems not to be consisted with these.

Do you have a proposed solution to this conflict? Would it be better to remove the MUST assertion from WoT Profile and stick to the SHOULD assertion from the Thing Description so that all the fallbacks can be used? I note that the Thing Description only makes the @language member mandatory if dynamic language negotiation has taken place (i.e. other languages are available which are not included in the current Thing Description).

Also, there should be some mention about which language should be applied for reply of property request, write property, or action in protocol bindings.

As far as I'm aware there are no human-readable strings used by these operations which would be used directly in generating a user interface. Any semantic meaning implied by responses to operations should be interpreted by the Consumer so that it can generate its own user interface and provide its own strings (e.g. strings to represent the status of an action or a human-readable version of enum value or unit). Is there something in particular you think may need to be localised at the protocol level?

[himorin]

• This section has MUST clause to include default language in @context array, but examples in this spec (e.g. example 1, example 2, example 4) do not have such.
• In 6.3.2 Human-Readable Metadata in WoT Things Description, handling of language is discussed in detail and fallback is also defined (like quoted below). This section seems not to be consisted with these.

Do you have a proposed solution to this conflict? Would it be better to remove the MUST assertion from WoT Profile and stick to the SHOULD assertion from the Thing Description so that all the fallbacks can be used? I note that the Thing Description only makes the @language member mandatory if dynamic language negotiation has taken place (i.e. other languages are available which are not included in the current Thing Description).

Thank you for this comment. I now think I've mis-read the text that Default Language is to specify a default language to be chosen by consumer from available list of supported languages in a Thing Description, but is not to tell a default language of string provided through asset. Is this correct?
If so, I think a phrase a name-value pair that defines the default language for the Thing Description is a bit unclear, and would propose to have some reference to language negotiation part of WoT TD.

Also, there should be some mention about which language should be applied for reply of property request, write property, or action in protocol bindings.

As far as I'm aware there are no human-readable strings used by these operations which would be used directly in generating a user interface. Any semantic meaning implied by responses to operations should be interpreted by the Consumer so that it can generate its own user interface and provide its own strings (e.g. strings to represent the status of an action or a human-readable version of enum value or unit). Is there something in particular you think may need to be localised at the protocol level?

If above mis-read happened, I believe this part of original comment does not be applicable, also.

[benfrancis]

Thank you for this comment. I now think I've mis-read the text that Default Language is to specify a default language to be chosen by consumer from available list of supported languages in a Thing Description, but is not to tell a default language of string provided through asset. Is this correct?

As I understand it a Thing Descriptions can have title and description members or titles and descriptions members, or a combination of both. With titles and descriptions members the language of the string is indicated as a key in the language map, e.g.

    "titles": {
        "en": "MyThing",
        "de": "MeinDing",
        "ja": "私の物",
        "zh-Hans": "我的东西", 
        "zh-Hant": "我的東西"
    },

With title and description members the language can be indicated by the @language member inside @context, e.g.

    "@context": [
        "https://www.w3.org/2022/wot/td/v1.1",
        { "@language": "en" }
    ],
    "title": "MyThing",
    "description": "Human readable information.",

Where there are both title/description and titles/descriptions members, the strings in title/description members are considered the "default" strings. I assume that's where the phrase "a name-value pair that defines the default language for the Thing Description" comes from.

In the Thing Description specification, the @language member is only mandatory if the language of the title and description members has been selected as a result of language negotiation (e.g. using the Accept-Language header in HTTP), indicating the result of the negotiation.

The Profile specification adds an additional assertion which says there must always be a @language member in the Thing Description, regardless of whether title/description or titles/descriptions are used, and regardless of whether localisation is performed using language maps inside the Thing Description or language negotiation at the protocol level.

On reflection, I think this assertion is probably over the top. In cases where a Thing Description only provides titles/descriptions members and does not provide title/description members (e.g. Example 9 in the Thing Description specification), the @language member is not useful (except for denoting the language of the top level title member which is always mandatory).

My personal suggestion would be to remove this assertion (and therefore the Default Language section of the Profile specification), and just stick to the Thing Description assertions which say the @language member is only mandatory if language negotiation is used for localisation (where only the use of title and description members is recommended).

In my experience from TestFests/PlugFests, most Thing Descriptions do not contain a @language member.

You could argue it's good practice to always provide a @language member when only title and description members are used (e.g. for accessibility reasons, since in theory if the strings are used to generate a user interface and the UI technology being used supports language annotations then it could help screen readers use the correct pronunciation), but I think that should just be a recommendation in the Thing Description specification since it applies to all Thing Descriptions, not just those which conform to a profile. (There's work planned in the next charter around defining best practices and "linting" of Thing Descriptions).

What do you think?

[himorin]

My personal suggestion would be to remove this assertion (and therefore the Default Language section of the Profile specification), and just stick to the Thing Description assertions which say the @language member is only mandatory if language negotiation is used for localisation (where only the use of title and description members is recommended).

I personally have no position on the TD specification whether to allow using @language to specify a single default language or to allow having both title and titles, but I would agree on removing Default Language section which results to let the TD specification define all constraints on TD into which profile entries are pushed, and keep Profiles specification just to define mappings for forms values.
(for former point, from i18n point of view, having default language expressly should be better since localized strings in e.g. titles array could have the same values especially for short terms - which results into failure of guessing the language of title.)

[mlagally]

A simple fix to the problem would be to update the examples to correspond to the normative language.