Merge pull request #472 from IIIF/0346-multilingual-annotation-body

Recipe #346 Support multiple languages in an Annotation body

_includes/links.md

@@ -69,6 +69,7 @@
 [0318]: {{ site.cookbook_url | absolute_url }}/recipe/0318-navPlace-navDate/ "Locating an Item in Place and Time"
 [0326]: {{ site.cookbook_url | absolute_url }}/recipe/0326-annotating-image-layer/ "Annotate a specific images or layers"
 
+[0346]: {{ site.cookbook_url | absolute_url }}/recipe/0346-multilingual-annotation-body/ "Annotating in Multiple Languages"
 [0377]: {{ site.cookbook_url | absolute_url }}/recipe/0377-image-in-annotation/ "Image in annotation"
 
 [0466]: {{ site.cookbook_url | absolute_url }}/recipe/0466-link-for-loading-manifest/ "Loading a manifest with a viewer using a link"

index.md

@@ -93,6 +93,7 @@ _(leading on to segmentation examples later)_
 * [Embedded or Referenced Annotations][0269]
 * [Linking external Annotations targeting a Canvas to a Manifest][0306]
 * [Image in annotations][0377]
+* [Annotating in Multiple Languages][0346]
 
 ## Internal structure
 

recipe/0118-multivalue/index.md

@@ -39,6 +39,7 @@ In this example, the work has multiple titles in both English and French. The Ma
 
 * [Internationalization and Multi-language Values][0006]
 * [Metadata][0029]
+* [Annotating in Multiple Languages][0346]
 
 {% include acronyms.md %}
 {% include links.md %}

recipe/0346-multilingual-annotation-body/index.md

@@ -0,0 +1,54 @@
+---
+title: Annotating in Multiple Languages
+id: 346
+layout: recipe
+tags: annotation
+summary: "tbc"
+viewers:
+ - Annona
+topic: 
+ - annotation
+---
+
+## Use Case
+
+You would like to make a text annotation in multiple languages on an image. Because the annotations are semantically equivalent, the expectation is that the user or client would choose which language to display for the annotation.
+
+## Implementation Notes
+
+To include language variation within any single annotation, combine the Choice structure, explained more fully in [Multiple Choice of Images][0033] and [Multiple Choice of Audio Formats][0434] with the appropriate annotation structure, for example the simple version shown in [Simple Annotation — Tagging][0021].
+
+When there are multiple equivalent annotations from which a user or client should select one, we use the Choice structure. While much of the IIIF specification uses language maps to distinguish between languages, Annotations use a language property with a value. Clients may process this mechanisim for multiple languages differently to language maps and the web annotation specification gives the following guidance:
+
+> "Clients MAY use any algorithm to determine which resource to choose, and SHOULD make use of the information present to do so automatically, but MAY present a list and require the user to make the decision." *— from [Choice Between Bodies](https://www.w3.org/TR/annotation-model/#choice-between-bodies)*
+
+The `body` of an Annotation uses the Choice structure, with each of its items differing only in the `language` and `value` properties. Note that an annotation's `value` and `language` in a Choice are represented as separate properties, unlike Manifest properties that use language maps.
+
+Somewhat as with the [Multiple Choice of Audio Formats][0434] recipe, the nature of the choice in this recipe is shared among the manifest creator, the visitor, and the client. The manifest creator defines the preferred order of languages by the top-to-bottom order of each `item` in the Choice structure. The visitor uses a client's interface elements to know what manifest data is available in multiple languages and which languages, as well as to make an active choice of which to display. A client may be programmed to take actions based on the W3C Web Annotation Data Model section on "Choice Between Bodies" cited above. If the client chooses to display a choice, the [W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/) says it should only display one. By the same token, user experience with a client will be improved if a client indicates different language versions of an annotation even if it shows only one initially.
+
+## Restrictions
+
+None known.
+
+## Example
+
+In this example, the image is from one of a pair of six-fold screens depicting four noble accomplishments in Azuchi-Momoyama period Japan (16th/17th century CE). At its [original online home](https://emuseum.nich.go.jp/detail?langId=en&webView=&content_base_id=100320&content_part_id=0&content_pict_id=0) item text exists in four languages. To simplify things here, only Japanese and English are used.
+
+There's one annotation, which focuses on the koto of the item's title (albeit enclosed in a cover and thus implied rather than shown). The text of the annotation takes that implication into account and describes this portion of the screen as representing a koto wrapped in a cloth.
+
+Terms of use for this image from the e-Museum of the National Institutes for Cultural Heritage in Japan / e国宝に 独立行政法人国立文化財機構 can be found in <a href="https://emuseum.nich.go.jp/about?langId=ja">Japanese</a>, <a href="https://emuseum.nich.go.jp/about?langId=en">English</a>, <a href="https://emuseum.nich.go.jp/about?langId=zh">Chinese</a>, and <a href="https://emuseum.nich.go.jp/about?langId=ko">Korean</a>.
+
+{% include manifest_links.html manifest="manifest.json" %}
+
+{% include jsonviewer.html src="manifest.json" config='data-line="58-72"' %}
+
+## Related Recipes
+
+* [Multiple Choice of Images in a Single View (Canvas)][0033] to see the Choice structure in an image context
+* [Multiple Choice of Audio Formats in a Single View (Canvas)][0033] to see the Choice structure in an A/V context
+* [Simple Annotation — Tagging][0021] for an Annotation using the tagging `motivation`
+* [Displaying Multiple Values with Language Maps][0118] to see a different way of casting a property value to a language.
+
+{% include acronyms.md %}
+{% include links.md %}
+

recipe/0346-multilingual-annotation-body/manifest.json

@@ -0,0 +1,82 @@
+{
+  "@context": "http://iiif.io/api/presentation/3/context.json",
+  "id": "{{ id.url }}",
+  "type": "Manifest",
+  "label": {
+    "en": [
+      "Koto, chess, calligraphy, and painting"
+    ],
+    "ja": [
+      "琴棋書画図屏風"
+    ]
+  },
+  "items": [
+    {
+      "id": "{{ id.path }}/canvas/p1",
+      "type": "Canvas",
+      "height": 31722,
+      "width": 70399,
+      "items": [
+        {
+          "id": "{{ id.path }}/page/p1/1",
+          "type": "AnnotationPage",
+          "items": [
+            {
+              "id": "{{ id.path }}/annotation/p0001-image",
+              "type": "Annotation",
+              "motivation": "painting",
+              "body": {
+                "id": "https://iiif.io/api/image/3.0/example/reference/36ca0a3370db128ec984b33d71a1543d-100320001004/full/full/0/default.jpg",
+                "type": "Image",
+                "format": "image/jpeg",
+                "height": 31722,
+                "width": 70399,
+                "service": [
+                  {
+                    "id": "https://iiif.io/api/image/3.0/example/reference/36ca0a3370db128ec984b33d71a1543d-100320001004",
+                    "profile": "level1",
+                    "type": "ImageService3"
+                  }
+                ]
+              },
+              "target": "{{ id.path }}/canvas/p1"
+            }
+          ]
+        }
+      ],
+	  "annotations": [
+		{
+		  "id": "{{ id.path }}/page/p2/1",
+		  "type": "AnnotationPage",
+		  "items": [
+			{
+			  "id": "{{ id.path }}/annotation/p0001-comment",
+			  "type": "Annotation",
+			  "motivation": "commenting",
+			  "body": [
+			  {
+			  	"type": "Choice",
+			  	"items": [
+					{
+						"type": "TextualBody",
+						"value": "Koto with a cover being carried",
+						"language": "en",
+						"format": "text/plain"
+					},
+					{
+						"type": "TextualBody",
+						"value": "袋に収められた琴",
+						"language": "ja",
+						"format": "text/plain"
+					}
+			  	]
+			  	}
+			  ],
+			  "target": "{{ id.path }}/canvas/p1#xywh=1650,1200,925,1250"
+			}
+		  ]
+		}
+	  ]
+    }
+  ]
+}