cookbook-recipes
cookbook-recipes copied to clipboard
IIIF
Recipe #0346 Support multiple languages in an Annotation body
Annotating in Multiple Languages
This PR addresses #346, for making annotations in multiple languages
Use case
[Draft] You have an annotated artifact intended for viewing by a global or other polylingual audience. So that as many of them as possible and practical are able to understand the annotations on your artifact, you want to present each annotation in multiple languages.
Hi Trip,
The editors would like to see the recipe before it goes to the TRC on Wednesday if possible.
Comments:
- Regarding the extra rights information could you remove the rights, requiredStatement and metadata elements from the manifest and add the information to the page. The multilingual label is fine. This is just to cut down the manifest so the detail of annotation isn't lost.
- Could you add highlighting.
- Also the changes you noted with the image from fixtures and the Japanese annotation text. Call out how the choice is different in the language map.
Use case
Change the following: “You have an image that you want to annotate for viewing by a global or other polylingual audience. So that as many of your intended audience as possible and practical are able to understand the annotations on your artifact, you want to present each annotation in some or all of their languages.” So something more concise like: “You would like to annotate an image with text in multiple languages. In this case the annotations are equivalent and the expectation is that the user or viewer would choose the language to view the annotation.
Implementation notes
Paragraph 1: Remove - “This recipe introduces one practical real-world situation for doing that.”
Second paragraph could you rewrite to something similar to:
Since we have multiple equivalent annotations which a viewer should select to show one, we would 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 https://www.w3.org/TR/annotation-model/#choice-between-bodies (Glen: There was a long discussion on how language maps differ from language in annotaitons and how much the viewer should make the decision on which is shown and how much the user is given a choice. In the end we decided to quote the annotation spec).
Reword:
The manifest creator defines the preferred order of languages, the visitor’s browser sends to the client its preferred language, and the client negotiates the interaction of the preceding to provide an interface to the visitor.
To:
The manifest creator defines the preferred order of languages, by the order of the items in the choice. Clients may make a choice using the note mentioned above. (Glen: we wanted to retain the order implied by Choice but we couldn't see a requirement for the browser to send a language to a client. If a Client wanted to do this then they could choose to.)
Reword last paragraph from: "For the user interface to the multiple language versions of an annotation, a client is expected to provide a visitor with a clear way to know there are equivalent annotations in multiple languages, with identifying information about which languages are in use, and with a way to switch between languages at will.” to: "There are many situations where the items in a choice may have a different language so it would be helpful if the client could indicate to the user that there are different versions of the annotation even if the viewer has made a choice to only show one initially. For example one item in the choice may be a translation. " (Glen: There was a long discussion on whether a client should or had to show all options but the W3C anno spec doesn't mention anything. So we've weakened the requirment in the text to be helpful rather than expected)
Comments from the editors:
Use case
Suggest changing this phrase in the use case:
“the expectation is that the user or client would choose the language to view the annotation”
to something like:
“the expectation is that the user or client would choose which translation to display for the annotation.”
Implementation notes
In the penultimate paragraph in the implementation notes section “(It is expected that any client will be capable of displaying the entire Unicode set, obviating client-based reasons to conceal any annotation language version.)” - do we need this?
In the same paragraph: “A client may be programmed to take actions based on the quoted W3C Web Annotation Data Model section above.” - maybe it’s important to point out that choice requires that the client display one and only one of the choices (it decides which one)
The final paragraph in implementation notes seems be carrying a lot. I would probably remove “There are many situations where the items in a Choice may have varying languages” as i don’t think it adds anything and feels like a transition to something else. Then simplify the rest: “User experience with a client will be improved if the client provides the user with a list of choices between which they can toggle…” — or something like that
Example
Second para in Example “There’s one annotation, which focuses..” - I assume we don’t use contractions? And no comma needed before “which”
maybe it’s important to point out that choice requires that the client display one and only one of the choices (it decides which one)
However — and the quoted text is what notes this — a client may display no option initially. My text tries to remind the reader in a new context about the quote. On the other hand, my text does leave unstated that if the client is programmed to display something, it should only select one, and I'll rectify that.
In the penultimate paragraph in the implementation notes section “(It is expected that any client will be capable of displaying the entire Unicode set, obviating client-based reasons to conceal any annotation language version.)” - do we need this?
I've come around to thinking the situation is less that we don't need it and more that it's not true. Remembering that we are writing for unknown and as-yet-uncreated clients, there's no particular reason a client couldn't be targeted at a particular language and have its own logic therefore of how to handle language choice. Coming from a hegemonic language and wanting to resist that hegemony, I was aiming at anglophone client creators to say that they should show all the languages available rather than only using English, but that's not well-placed here.
Then simplify the rest: “User experience with a client will be improved if the client provides the user with a list of choices between which they can toggle…” — or something like that
I'm leaning on the "something like that" part 😄 because we don't want to be implicitly prescriptive about how the client gives the user knowledge of and control over the choice option to display. Agree that the graf is clunky, and with edits I've run it into the previous graf.
Second para in Example “There’s one annotation, which focuses..” - I assume we don’t use contractions? And no comma needed before “which”
We use contractions plenty, and if there were no comma, it would need to be "that" instead. (It's not as hard and fast a delineation in standard American English as it used to be, but I maintain the distinction.) It's also true that the "which" introduces a non-restrictive clause, so it takes a comma.
However, the "albeit . . . " clause should be a parenthetical, which I've done. And seeing that draws my attention to removing the ToU information from parentheses.
(To be fair, we don't use too many * + "is" contractions per se. Lots of negation contractions, though: "don't", "doesn't", "isn't", "won't".)
On the "no comma" comment -- in this case, the which clause seems to be essential to the meaning of the sentence, no? Maybe it should be "that" instead of "which"?
I think I get how we are reading this "which" sentence differently - I'm reading it as "There's one (particular) annotation..", meaning "this one in particular, perhaps out of several". But you are saying "This example has a single annotation...". Hence the disagreement re: the comma.
I agree about the ways we are thinking/reading the which/that issue here. The grammar drilled into me split usage into "that" for "one of many" and "which" for "this particular one". I've learned that both British English and more modern AmEnglish usage makes much less of a distinction.