Re: [w3c/manifest] [DRAFT—DO NOT MERGE/REVIEW] Add members for localization (PR #1101)

@aphillips commented on this pull request.



> +          This member is a [=localizable member=]. Setting a [=text-direction=]
+          is not supported and will be ignored.

It would probably be better (since you don't redefine the serialization) to say something like:

```suggestion
          This member is a [=localizable member=].
          Setting the [=text direction=] of an icon has no meaning:
          any direction set SHOULD be ignored by consumers.
```

> +          A <dfn>localizable member</dfn> is a [=manifest=] member that can be
+          localized. Each [=localizable member=] of the [=manifest=] has a
+          corresponding <dfn>localized member</dfn> with the suffix

This is really hard to read, in that `localizable member` and `localized member` are super similar looking. Consider separating the terms somewhat more?

> A `localizable member` is a _manifest_ member that can be localized.
> This can include translation or other locale-based customization.
> When present, the localized representations of a `localizable member`
> appear in a corresponding member with the suffix `_localized`. ...


> +          [=Localized members=] contain a [=localization map=] that defines
+          [=localized values=] for different locales denoted by a [=language
+          tag=]. If present and if the [=localization map=] contains a
+          [=localized value=] that matches the user's localization settings,
+          the user agent SHOULD override the value of the [=localizable
+          member=].

I would probably explain this differently? For one thing, I think it is not helpful to talk about the localizations "overriding" the value. It's not really an override: it **_is_** the value. The `name` (etc.) is the _default_, used when no applicable localized value is available. The default has a locale associated with it (represented by the `lang` member), but the application does not do language matching against this value. 

Perhaps something like:

```suggestion
A [=localized member=] contains a [=localization map=] that provides
[=localized values=] for the given [=localizable member=] in the application.
Each [=localized value=] is identified by a [=language tag=].
The user agent SHOULD use the user's localization settings to select
the [=localized value=] whose language tag best matches the user's preference.
When no such [=localized value=] is available, the default representation is used.
```


> +          localized. Each [=localizable member=] of the [=manifest=] has a
+          corresponding <dfn>localized member</dfn> with the suffix
+          `_localized`. For example, the [=manifest/name=] member is a
+          [=localizable member=], where `name_localized` is the corresponding
+          [=localized member=].
+        </p>
+        <p>
+          [=Localized members=] contain a [=localization map=] that defines
+          [=localized values=] for different locales denoted by a [=language
+          tag=]. If present and if the [=localization map=] contains a
+          [=localized value=] that matches the user's localization settings,
+          the user agent SHOULD override the value of the [=localizable
+          member=].
+        </p>
+        <aside class="example" title=
+        "Overriding the application name with localized values">

As noted, I'd prefer not to talk about "overriding". Perhaps:

```suggestion
        "Localizing the application name">
```

> +              "lang": "en-US",
+              "name": "Color Picker",
+              "name_localized": {
+                "en-GB": "Colour Picker",
+                "fr": "Sélecteur de Couleur"

I think you'd be better off showing the whole enchillada up front? (My localized example is stolen verbatim from [string-meta](https://w3c.github.io/string-meta/#language-maps) and is meant to be illustrative only)

```json
"lang": "en-US",
"dir": "ltr",
"name": "Color Picker",
"name_localized": {
    "en":    {"value": "This is English"},
    "en-GB": {"value": "This is UK English", "dir": "ltr"},
    "fr":    {"value": "C'est français", "lang": "fr-CA", "dir": "ltr"},
    "ar":    {"value": "هذه عربية", "dir": "rtl"}
}
```

> +          text direction for a localized value. This is needed for situations
+          where a term or text must be presented in a language different from
+          the user's set language.

This covers the language tag not matching the language map key case (which is rare). However, the far more common requirement is that the direction of the translation does not match the default direction of the application. For example, every right-to-left value will need this when the default language of the application is a left-to-right language (or vice versa).

As a result, I would leave out "text direction" in the note and mention direction separately.

> +          This member is a [=localizable member=]. Setting a [=text-direction=]
+          is not supported and will be ignored.

see above comment

> +              </li><!-- todo: any existing algorithm for this? -->
+              <!-- todo: also take manifest's own lang into account -->

What's wanted here is `Intl.LocaleMatcher`, which is not yet beyond the proposal stage.

Language tag matching is complicated. It is case _insensitive_ and there can be some quirks if one wants the "best fit" style of matching. If one is okay with BCP47 Lookup matching, things are somewhat simpler: one selects the _longest_ tag that is a prefix of the user's requested value (or the default if no tag is a prefix). BCP47 [describes this](https://www.rfc-editor.org/rfc/rfc4647.html#section-3.4) in terms of truncating the requested tag until a match is found (or use the default if no match is found):

```
   Range to match: zh-Hant-CN-x-private1-private2
   1. zh-Hant-CN-x-private1-private2
   2. zh-Hant-CN-x-private1
   3. zh-Hant-CN
   4. zh-Hant
   5. zh
   6. (default)
```

Note that the manifest's own language should not participate in this. It has a language associated with it, but it is the "root locale" default value for purposes of language negotiation.

This could be a bit weird, since the localized value might override the manifest's default language (e.g. the default language is never visible)

-- 
Reply to this email directly or view it on GitHub:
https://github.com/w3c/manifest/pull/1101#pullrequestreview-2105001533
You are receiving this because you are subscribed to this thread.

Message ID: <w3c/manifest/pull/1101/review/2105001533@github.com>