Use the JSON-LD keywords for international texts

[iherman]

Section

https://w3c.github.io/epub-specs/epub34/annotations/#body

Describe the problem

The Body object uses the language and textDirection terms for international texts. This is inherited from the Web Annotation spec, which was created when text directionality was not properly handled in JSON-LD. However, JSON-LD now has the @language and @direction keywords that properly covers this, see String Internationalization.

Describe the fix or new feature you propose

I would propose to rely on the JSON-LD spec, possibly aliasing the language and direction terms to the keywords.

[HadrienGardeur]

I would propose to rely on the JSON-LD spec, possibly aliasing the language and direction terms to the keywords.

Would you like to:

• use @language and @direction directly instead of language and textDirection?
• map them in an JSON-LD context document?

[iherman]

I would propose to rely on the JSON-LD spec, possibly aliasing the language and direction terms to the keywords.

Would you like to:

• use @language and @direction directly instead of language and textDirection?
• map them in an JSON-LD context document?

first of all, whichever we choose, the difference is that these properties will not be bound to the body, and can be used elsewhere, because they are json ld keywords.

Personally I am not fond of "hiding" the json-ld keywords with aliases, it can be misleading. Ie, my personal choice would be to use the keyword form. But we (and the Web annotation spec) already aliases @type and @value, so a consistent approach would be to alias them to language and direction or textDirection.

I anticipated that in the json-ld context file I generate with my tool: https://github.com/iherman/ea-vocabulary/blob/main/vocabulary.context.jsonld

[iherman]

The other problem we have in the current specification is that we do not have means of our own to set the language/direction values elsewhere. Consider the (somewhat larger) Example in the spec:

• The title is in French, but it is not explicitly said anywhere
• The about is on a publication whose title and publisher are English
• The body of the annotation item is presumably in French but it is not said anywhere either

The current specification has a solution for the third item only.

We could redefine the language and textDirection to be valid anywhere in our structure. But we are then creating our own variant of these properties which should also include an inheritance mechanism (if I set the language on the annotation set level, it should be valid on all objects except if redefined down in the tree). This can also be done, but we would be duplicating a mechanism that is already present in JSON-LD. It would not clash with JSON-LD but it is, specification-wise, ugly.

However... the syntax in JSON-LD, though exists, and processors implement it, does not help us in keeping things tidy. Here is a reproduction of the essence of the aforementioned example with bona fide JSON-LD syntax:

{
    "@context": [
        "https://www.w3.org/ns/epub-anno.jsonld",
        {
            "@language" : "fr",    // French is the language for strings, unless stated otherwise
            "@direction" : "ltr"   // Text is left-to-right, unless stated otherwise
        }
    ],
    "id": "urn:uuid:123-123-123-123",
    "type": "AnnotationSet",
    "title": "Annotations Mme Prof, La Peste, cours 1ère B",
    "about": {
        // Everything is in UK English for about
        "@context" : {
            "@language": "en-uk"
        },
        "dc:title": "Alice in Wonderland",
        "dc:publisher": "Example Publisher",
    },
    "items": [
        {
            "id": "urn:uuid:234-234-234-234",
            "type": "Annotation",
            "target": {},
            "body": {
                "value": "J'adore!"    // This is in French, the 'default' language
            }
        },
        {
            "id": "urn:uuid:235-235-235-235",
            "type": "Annotation",
            "target": {},
            "body": {
                "value": {
                    "@language" : "hu",
                    "string" : "Imádom!" // This text is in Hungarian
                }
            }
        }
    ]
}

There are two awkwardness in this:

• When used within a context, a keyword cannot be aliased in JSON-LD. Hence the need to use @language instead of language when used in a context.
• For the string in the body, there are some hacky stuffs happening behind the scene:

  • If you look at the JSON-LD spec in i18n, it allows for a construction of the kind:

    "occupation": {
      "@value": "Scientist",
      "@language": "en"
    }

    which may avoid using a @context in the body. However, there is then the (annotation) value that is used in the body, and @value as a JSON-LD keyword, i.e., we would have:

    "body" : {
        "value" : {
            "@language": "hu",
            "@value" : "Imádom"
        }
    }

    which many would feel confusing. The trick is to introduce the string term, that is, in fact,
    an alias to the JSON-LD keyword.

All things considered, I still believe that we should move towards the JSON-LD solution and deviate on this from the Web Annotation Model. In practice it would mean:

• removing the language and textDirection entries from the definition of body
• adding a separate (informal) section explaining the relevant portions of the JSON-LD specification; I would think that the example above, plus some explanation, would do the trick.
• we could alias the term language to @language and, thereby, make the @ character removed when combines with string above. Not sure it is worth the trouble, and it might be actually confusing.

CC @pchampin, maybe he has some good ideas to make this a bit more palatable...

[iherman]

we could alias the term language to @language and, thereby, make the @ character removed when combines with string above. Not sure it is worth the trouble, and it might be actually confusing.

Actually, we should not. The reason is that, per the JSON-LD spec, keyword aliases must not be used within a @context setting, only in the real data. This means that the only case when the aliased version could be used is in the last, Hungarian example; the other cases must use the original version. That would be way too confusing and error prone...

[iherman]

Note to myself: this may also lead to some updates on the vocabulary. At the moment, the range of strings is xsd:string. However, for all properties whose values are, possibly language tagged string the range must be

xsd:string ⊔ rdf:langString ⊔ rdf:dirLangString

(This is just a simple modification of the vocabulary file does not affect anything else.)

[iherman]

@llemeurfr @HadrienGardeur do you have any objection to this? To move things ahead I would propose to create a PR with the necessary changes, with the modification/removal/addition of the terms and (I believe that may be the best approach) adding a separate "Internationalization consideration" to describe the mechanism inherited from JSON-LD with also an example. Is it o.k. if I do this?

[iherman]

This was discussed during the pmwg meeting on 19 March 2026.

View the transcript

Use JSON-LD keywords for language and direction - w3c/epub-specs#2950

<ivan> w3c/epub-specs#2854

wendyreid: ivan, can you explain this topic?

ivan: we have to talk about language and language direction in strings in annotations

<LaurentLM> link to the body language and textDirection: https://w3c.github.io/epub-specs/epub34/annotations/#body

ivan: the current draft has a field for text direction that has two problems.
… it is only for the body and doesn't solve other text, like titles and descriptions
… json LD now has a built-in feature to set language and direction
… my original issue is that we should use what we get in jsonLD
… and not duplicate things. It would solve the missing setting for other natural language text fields
… I've defined the solution and written a PR that we use JSON LD
… I described part of the JSON LD that are usable in my view in annotaitons
… i dont want to go into detail in the syntax
… if we set another block we can use JSON LD to set the language and direction
… it would then apply to everything in the tree underneath
… you can still have local overrides
… two open questions that need a decision
… there is a way in the JSON LD syntax to set the language and direction in a single text field
… which uses a different syntax and can be confusing
… we may not have to specify values for single strings
… I don't think we need to add this to the spec
… I would like some feedback on this
… is it a must to add language and direction?
… or is it a should? We should do the same for the annotations spec
… this has a slight effect on the vocabulary so we should make a decision

mgarrish: we don't have a requirement in the package document, but it is required for accessibility
… setting the language of the publication is required, but not setting the language of the HTML

ivan: in the pacakge doc, if we say it is a must to specify the DC language, the we should do the same for the annotations spec

LaurentLM: web annotations are based on JSON LD
… programmers work with JSON not JSON LD
… to go too far with JSON LD is dangerous for developers
… using language direction is a small improvement for annotaitons
… I would like to see that use case for adding language and language direction before we implement this
… we had this same discussion with web publications. The outcome was to
… web publication spec can give us some continuity

<LaurentLM> Readium Web Publications: https://readium.org/webpub-manifest/contexts/default/#title

LaurentLM: readium web publications have chosen another path
… if you want multiple languages you use the language code, language is mapping to JSON LD

<LaurentLM> W3C WEb Publications: https://www.w3.org/TR/pub-manifest/#manifest-lang-dir-local

LaurentLM: this seems easier to master than the example in the web publication W3C spec

ivan: I realized while doing this, that what we have in web publications is buggy
… you cannot use the alias within the context

LaurentLM: having the abilty specify language locally is important
… to have it at the top, and setting the direction, at the top makes sense

ivan: it is clear that we cannot use language and direction in the body that the way it is now
… it is not now the JSON LD specification, you cannot specify the language and have it be recognized
… the mapping you have in Readium is valid JSON LD and can be used
… but since it doesn't handle direction we might have problems with internationalization
… we rarely have a case where we want to express the same thing with 3 different languages

sueneu: Use cases are rare where you want to say things in different languages
… but I do this all the time

ivan: In general that is true, but the question is does this happen in annotations

sueneu: Absolutely. This could be very helpful
… you could have English annotations

ivan: that is not really what we are talking about. We need to specify the language you made the annotation in

@laurentLM it looks like this needs more discussion

@gman: I think there is a use case here, which could be annotation of a translation and discussion that could take place in two languages

wendyreid: this could be more about the accessiblity issue where if the language isn't marked up properly screen readers can lead to some interesting publications
… in theory, I could add a word in a second language within an annotation

ivan: which leads us to the discussion of HTML in annotations
… if we can use markdown in the body, like the markdown in github
… that does allow some HTML, so you could manually set a span with the correct language tag, it would cover that issue
… if we really what to mix the language inside the body, we could use multiple bodies

duga: Github technically doesn't support HTML but doesn't strip them out
… so it displays correctly in a browser
… I don't know if there is a version of Markdown that allows Ruby
… I'm not even sure markdown will make it through rec

@ivan: for those issues, we will have face an international review,
… if we cannot set the language and direction in the right place, we will not get the sign off

wendyreid: Let's leave it at that, we have more to do on the language question
… otherwise, thank you everyone for a great meeting. See you all next week

---