Skip to content

Commit 3b8a92f

Browse files
christianliebelchristianliebel
committed
Add members for localization
1 parent 55e6818 commit 3b8a92f

File tree

1 file changed

+177
-24
lines changed

1 file changed

+177
-24
lines changed

‎index.html

+177-24
Original file line numberDiff line numberDiff line change
@@ -451,21 +451,6 @@ <h3>
451451
<a>manifest</a>. The [=manifest/dir=] member's value can be set to a
452452
<a>text-direction</a>.
453453
</p>
454-
<p>
455-
The <dfn>localizable members</dfn> are:
456-
</p>
457-
<ul>
458-
<li>[=manifest/name=] member.
459-
</li>
460-
<li>[=manifest/short_name=] member.
461-
</li>
462-
<li>[=Shortcut item's=] [=shortcut item/name=] member.
463-
</li>
464-
<li>[=Shortcut item's=] [=shortcut item/short_name=] member.
465-
</li>
466-
<li>[=Shortcut item's=] [=shortcut item/description=] member.
467-
</li>
468-
</ul>
469454
<p>
470455
The <dfn>text-directions</dfn> are the following, implying that the
471456
value of the <a>localizable members</a> is by default:
@@ -593,7 +578,7 @@ <h3>
593578
"manifest">name</dfn></code> member is a <a>string</a> that
594579
represents the name of the web application as it is usually displayed
595580
to the user (e.g., amongst a list of other applications, or as a
596-
label for an icon).
581+
label for an icon). This member is a [=localizable member=].
597582
</p>
598583
<p>
599584
The [=manifest/name=] member serves as the <a data-cite=
@@ -614,7 +599,8 @@ <h3>
614599
"manifest">short_name</dfn></code> member is a <a>string</a> that
615600
represents a short version of the name of the web application. It is
616601
intended to be used where there is insufficient space to display the
617-
full name of the web application.
602+
full name of the web application. This member is a [=localizable
603+
member=].
618604
</p>
619605
<p class="note" title="Processing the `short_name` member">
620606
When [=processing a manifest=], the [=process a text member=]
@@ -675,6 +661,10 @@ <h3>
675661
an <abbr title="Operating system">OS</abbr>'s task switcher and/or
676662
system preferences.
677663
</p>
664+
<p>
665+
This member is a [=localizable member=]. Setting a [=text-direction=]
666+
is not supported and will be ignored.
667+
</p>
678668
<aside class="note">
679669
<p>
680670
When [=processing a manifest=], the [=process image resources=]
@@ -1280,6 +1270,158 @@ <h3>
12801270
conventions or limitations of the host operating system.
12811271
</p>
12821272
</section>
1273+
<section>
1274+
<h3>
1275+
`*_localized` members
1276+
</h3>
1277+
<p>
1278+
A <dfn>localizable member</dfn> is a [=manifest=] member that can be
1279+
localized. Each [=localizable member=] of the [=manifest=] has a
1280+
corresponding <dfn>localized member</dfn> with the suffix
1281+
`_localized`. For example, the [=manifest/name=] member is a
1282+
[=localizable member=], where `name_localized` is the corresponding
1283+
[=localized member=].
1284+
</p>
1285+
<p>
1286+
[=Localized members=] contain a [=localization map=] that defines
1287+
[=localized values=] for different locales denoted by a [=language
1288+
tag=]. If present and if the [=localization map=] contains a
1289+
[=localized value=] that matches the user's localization settings,
1290+
the user agent SHOULD override the value of the [=localizable
1291+
member=].
1292+
</p>
1293+
<aside class="example" title=
1294+
"Overriding the application name with localized values">
1295+
<pre class="json">
1296+
{
1297+
"lang": "en-US",
1298+
"name": "Color Picker",
1299+
"name_localized": {
1300+
"en-GB": "Colour Picker",
1301+
"fr": "Sélecteur de Couleur"
1302+
}
1303+
}
1304+
</pre>
1305+
</aside>
1306+
<p>
1307+
The <dfn>localization map</dfn> is an [=ordered map=] whose key is a
1308+
[=language tag=] and whose value is a [=localized value=]. The
1309+
<dfn>localized value</dfn> represents the value applied for the
1310+
[=language tag=] specified as the key. The value matches the type of
1311+
its corresponding [=localizable member=]. For example, a [=localized
1312+
value=] for the [=manifest/name=] member could directly be a
1313+
[=string=].
1314+
</p>
1315+
<p class="note">
1316+
To support multilingual content and ensure proper display and
1317+
accessibility, it is possible to specify a different language tag and
1318+
text direction for a localized value. This is needed for situations
1319+
where a term or text must be presented in a language different from
1320+
the user's set language.
1321+
</p>
1322+
<p>
1323+
Alternatively, the [=localized value=] can be an [=ordered map=]
1324+
consisting of a `lang`, `dir`, and `value` member, where the `lang`
1325+
member is a [=language tag=], `dir` is a [=text-direction=], and
1326+
`value` contains the localization, matching the type of its
1327+
corresponding [=localizable member=]. The `lang` and `dir` members
1328+
are optional. When they are not set, `lang` matches the [=language
1329+
tag=] of the key, and `dir` matches the [=manifest/dir=] member of
1330+
the [=manifest=].
1331+
<!-- todo: maybe processed value of dir? or the default dir of the locale? -->
1332+
</p><!-- todo: better example -->
1333+
<aside class="example" title="Advanced localization example">
1334+
<pre class="json">
1335+
{
1336+
"lang": "en-US",
1337+
"dir": "ltr",
1338+
"shortcuts": [{
1339+
"description": "Change language",
1340+
"description_localized": {
1341+
"ar": { "lang": "en", "dir": "ltr", "value": "Change language" }
1342+
},
1343+
"icons": [{
1344+
"src": "/icons/play-later.svg",
1345+
"type": "image/svg+xml"
1346+
}],
1347+
"icons_localized": {
1348+
"ar": [{
1349+
"src": "/icons/ar/play-later.svg",
1350+
"type": "image/svg+xml"
1351+
}]
1352+
}
1353+
}]
1354+
}
1355+
</pre>
1356+
</aside>
1357+
<p>
1358+
<!-- todo: is there an "any" type? -->
1359+
To <dfn>normalize the localized value</dfn>, given |localizedValue|,
1360+
[=string=] |languageTag:string|, and [=ordered map=]
1361+
|manifest:ordered map|:
1362+
</p>
1363+
<ol class="algorithm">
1364+
<li>Let |normalizedValue| be an [=ordered map=].
1365+
</li>
1366+
<li>If |localizedValue| is an [=ordered map=], and "value"
1367+
[=map/exists=] in |localizedValue|:
1368+
<ol>
1369+
<li>[=map/Set=] |normalizedValue|["value"] to
1370+
|localizedValue|["value"].
1371+
</li>
1372+
<li>If "lang" [=map/exists=] in |localizedValue|, [=map/set=]
1373+
|normalizedValue|["lang"] to |localizedValue|["lang"].
1374+
</li>
1375+
<li>If "dir" [=map/exists=] in |localizedValue|, [=map/set=]
1376+
|normalizedValue|["dir"] to |localizedValue|["dir"].
1377+
</li>
1378+
</ol>
1379+
</li>
1380+
<li>If "value" does not exist in |normalizedValue|, [=map/set=]
1381+
result["value"] to |localizedValue|.
1382+
</li>
1383+
<li>If "lang" does not exist in |normalizedValue|, [=map/set=]
1384+
|result|["lang"] to |languageTag|.
1385+
</li>
1386+
<li>If "dir" does not exist in |normalizedValue|, [=map/set=]
1387+
|normalizedValue|["dir"] to |manifest|["dir"].
1388+
</li>
1389+
<li>Return |normalizedValue|.
1390+
</li>
1391+
</ol>
1392+
<p>
1393+
To <dfn>process a localizable member</dfn>, given [=string=]
1394+
|localizableMemberName| and [=ordered map=] |json|:
1395+
</p><!-- todo: use algorithm when processing manifest -->
1396+
<ol class="algorithm">
1397+
<li>Let |localizedMemberName| be the [=string/concatenation=] of the
1398+
[=list=] « |localizableMemberName|, "_localized" ».
1399+
</li>
1400+
<li>If |localizedMemberName| [=map/exists=] in |json|:
1401+
<ol>
1402+
<li>Let |localizedMember| be |json|[|localizedMemberName|].
1403+
</li>
1404+
<li>If |localizedMember| is not an [=ordered map=], continue.
1405+
</li><!-- todo: any existing algorithm for this? -->
1406+
<!-- todo: also take manifest's own lang into account -->
1407+
<li>Let |languageKey| be the most suitable language key based on
1408+
the user's localization settings from the [=map/keys=] of
1409+
|localizedMember|.
1410+
</li>
1411+
<li>If |languageKey| has a value, return the result of
1412+
[=normalize the localized value=], passing
1413+
|localizedMember|[|languageKey|], |languageKey|, and |manifest|.
1414+
</li>
1415+
</ol>
1416+
</li><!-- todo: ensure lang was set during processing -->
1417+
<li>If |localizableMemberName| [=map/exists=] in |json|, return the
1418+
result of [=normalize the localized value=], passing
1419+
|json|[|localizableMemberName|], |manifest|["lang"], and |manifest|.
1420+
</li>
1421+
<li>Otherwise, return.
1422+
</li>
1423+
</ol>
1424+
</section>
12831425
<section>
12841426
<h2>
12851427
Manifest life-cycle
@@ -1664,10 +1806,9 @@ <h3>
16641806
</dt>
16651807
<dd>
16661808
The user agent is free to display the icon where no [=manifest
1667-
image resource/purpose=] is required. For example, a
1668-
[=manifest image resource=] with a "any" purpose
1669-
wouldn't be used in a context where "[=icon purpose/monochrome=]"
1670-
is required.
1809+
image resource/purpose=] is required. For example, a [=manifest
1810+
image resource=] with a "any" purpose wouldn't be used in a context
1811+
where "[=icon purpose/monochrome=]" is required.
16711812
</dd>
16721813
</dl>
16731814
<p>
@@ -2043,7 +2184,7 @@ <h3>
20432184
The [=shortcut item's=] <code><dfn data-dfn-for=
20442185
"shortcut item">name</dfn></code> member is a <a>string</a> that
20452186
represents the name of the shortcut as it is usually displayed to the
2046-
user in a context menu.
2187+
user in a context menu. This member is a [=localizable member=].
20472188
</p>
20482189
</section>
20492190
<section>
@@ -2055,7 +2196,7 @@ <h3>
20552196
"shortcut item">short_name</dfn></code> member is a <a>string</a>
20562197
that represents a short version of the name of the shortcut. It is
20572198
intended to be used where there is insufficient space to display the
2058-
full name of the shortcut.
2199+
full name of the shortcut. This member is a [=localizable member=].
20592200
</p>
20602201
</section>
20612202
<section>
@@ -2066,7 +2207,8 @@ <h3>
20662207
The [=shortcut item's=] <code><dfn data-dfn-for=
20672208
"shortcut item">description</dfn></code> member is a <a>string</a>
20682209
that allows the developer to describe the purpose of the shortcut.
2069-
User agents MAY expose this information to assistive technology.
2210+
User agents MAY expose this information to assistive technology. This
2211+
member is a [=localizable member=].
20702212
</p>
20712213
</section>
20722214
<section>
@@ -2089,6 +2231,10 @@ <h3>
20892231
"shortcut item">icons</dfn></code> member lists images that serve as
20902232
iconic representations of the shortcut in various contexts.
20912233
</p>
2234+
<p>
2235+
This member is a [=localizable member=]. Setting a [=text-direction=]
2236+
is not supported and will be ignored.
2237+
</p>
20922238
</section>
20932239
<section>
20942240
<h3>
@@ -3320,6 +3466,13 @@ <h2>
33203466
using one of the following options:
33213467
</p>
33223468
<dl>
3469+
<dt>
3470+
Localized values in the manifest:
3471+
</dt>
3472+
<dd>
3473+
Authors can provide [=localized values=] for the [=localizable
3474+
members=] of the [=manifest=].
3475+
</dd>
33233476
<dt>
33243477
Dynamically setting the language:
33253478
</dt>

0 commit comments

Comments
 (0)