Matterhorn 11-004 · PDF/UA-1 UA1:7.2-3
Comments and link descriptions with no language
Annotation Contents strings — link descriptions, comments — have no determinable language.
The condition, as the protocol states it. “Natural language in the Contents entry for annotations cannot be determined.”
Matterhorn Protocol 1.1, checkpoint 11, index 11-004, section UA1:7.2-3. Software can decide this one on its own.
What a screen reader actually does
Link and comment text is announced in the wrong voice.
What the condition is
An annotation is an object on the page that is not page content: a link’s clickable area, a comment, a stamp, an attachment. Many carry a /Contents string:
19 0 obj
<< /Type /Annot
/Subtype /Link
/Rect [ 72 715 300 730 ]
/Contents (Privacy notice, opens example.gov)
/A << /S /URI /URI (https://example.gov/privacy) >>
/StructParent 1
>>
endobjFor a link, /Contents is the alternate description of where it goes, which 28-012 requires. For a comment it is the comment. For a stamp or an attachment it is what the thing is, which is 28-004. In every case it is text that can be presented to a reader and spoken aloud.
The string has no language entry of its own. The dependable way to give it one is the catalog’s /Lang, the document’s default language, which is also the only source Taggart consults. When the catalog has none, this condition fails for every annotation that has /Contents.
What the user hears
Whatever a screen reader speaks from /Contents comes out in its default voice. For an English description on an English-default machine that is fine. For a Hebrew comment, or a Hebrew link description, it is not speech in any useful sense.
Annotations are also text people meet out of context: a comment read from a list of comments, a link reached by tabbing. Whatever is spoken from /Contents arrives without the surrounding sentence to guess from, so if it is noise, there is nothing to recover the meaning from.
Where it comes from
No document language at all. The plain case, and the same cause as 11-001. One entry fixes both.
Languages set on elements but not on the catalog. Careful remediation sometimes puts /Lang on the Document element and leaves the catalog empty. The page text is then covered; the annotations, which Taggart judges from the catalog, are not.
Descriptions added after export. Link descriptions added to satisfy 28-012, stamps and attachments described for 28-004. Each adds a /Contents string to a file that may never have had a language.
Review comments left in. A reviewer’s notes, in the reviewer’s language, shipped with the document.
How to check it free
Acrobat Pro. Document properties → Advanced → Reading Options → Language. If it is blank and the file has links with descriptions or any comments, this condition fails. The comments themselves are listed in the Comments panel.
veraPDF tests every annotation that has /Contents for a determinable language.
Listen to it. Tab through the links with a screen reader running and listen to what each one is called. Ten seconds tells you whether the descriptions come out as words.
How to fix it free, in Acrobat Pro
From Adobe’s guide to checking accessibility:
- The hamburger menu (Windows) or the File menu (macOS) → Properties → Advanced.
- Under Reading Options, choose the language from the Language list, or type its code if it is not listed.
- OK, and save.
The Accessibility Checker’s route works too: select Primary Language, choose Fix from the options menu, and pick the language in the Set Reading Language dialog.
There is no per-comment alternative. Adobe’s comment properties cover the author and subject, appearance and review history, and nothing about language. That is one more reason to write published annotations in the document’s own language.
What Taggart does
Taggart checks this once per document. When the catalog /Lang is missing, or is not shaped like a BCP 47 tag, and at least one annotation on any page has a non-empty /Contents, it reports a blocker that counts them and points at the first by page and object number:
1 annotation(s) carry a /Contents string but the document has no valid /Lang, so their natural language cannot be determined.
It decides from the catalog alone. A /Lang on the Link or Annot element that holds the annotation does not clear the finding; only the catalog does.
The repair is document-language, which runs only when you approve it. In the app, ticking Set the document language shows the tag it will write, which starts as Taggart’s proposal: he-IL for Hebrew and ar for Arabic, from the letters; for text in Latin letters, the language its commonest words clearly point to — English, German, French, Spanish, Italian, Dutch, Portuguese or Polish. A page with too few words to tell gets en-US. Where the words point nowhere clearly, or the text is in another script, there is no proposal and the step asks you to type the tag. If that is not the document’s language, type the right one in the same repair step, or set the language in the program that made the file and export it again. The change log records the tag it wrote.
The fix writes the catalog /Lang and dc:language, and clears this finding along with any of 11-001, 11-003, 11-005 and 11-006 that came from the same missing entry.
Two of Taggart’s own repairs add /Contents: the link fix can use a link’s target address as its description when you ask it to, and the annotation fix writes the descriptions you give it. Neither sets a language. If the catalog has none, the strings they write are exactly what this condition reports, so the language fix belongs in the same run.
How Taggart handles it
Taggart checks for this condition automatically and reports it as a blocker, with where in the file it found it.
The fix is Set the document language. It changes what the document means, so Taggart proposes it and waits for your approval rather than applying it unattended.
Whatever Taggart changes, the page still looks identical. Fixes edit the PDF object model, not the content streams, and every remediation is re-rendered and compared against the original at structural similarity ≥ 0.999 before you get the file back. A tool that quietly reflows your document is worse than no tool.
Frequently asked questions
Which annotations does this cover?
Any annotation with a /Contents string: link descriptions, sticky-note and text-box comments, stamps, file attachments, a highlight with a note on it. Taggart counts every one on every page, hidden ones included, and reports them together with the page and object number of the first.
I set a language on the Link element. Why is it still reported?
Because Taggart decides this condition from the catalog alone. A /Lang on the structure element that holds the annotation is not consulted, so a document with no catalog /Lang is reported however carefully its elements are labelled. Set the document language; it is one entry and it covers every annotation at once.
The review comments are in English and the document is in Hebrew. What then?
Then whichever language you declare, part of the file is read in the wrong voice, and Acrobat's comment properties have no language setting to separate them. Comments that are meant to be published belong in the document's language. Review comments usually should not be in a published file at all.
Does fixing 28-012 make this worse?
It makes it apply. A link with no /Contents gives this condition nothing to examine; adding the description that 28-012 asks for creates a string that now needs a language. Set the document language first and every description written afterwards is covered.
Where this sits in the standards
| Standard | Reference |
|---|---|
| Matterhorn Protocol 1.1 | Checkpoint 11 (Declared Natural Language), index 11-004 |
| PDF/UA-1 (ISO 14289-1) | Clause 7.2-3 |
| WCAG 2.1 | 3.1.2 Language of Parts — Level AA |
| EN 301 549 / Section 508 / ADA Title II | All three point at WCAG 2.1 Level AA for non-web documents, so a Level A or AA criterion here is in scope for each of them. |
Related conditions
- 11-001 Natural language for text in page content cannot be determinedNo /Lang is in effect for some text: neither on the catalog, nor on an enclosing structure element, nor on a marked-content sequence.
- 28-012 A link annotation does not include an alternate description in its Contents entryLink annotations need /Contents describing where the link goes.
- 28-004 An annotation has neither a Contents entry nor an alternative descriptionEvery non-widget annotation needs an accessible description, either in its own /Contents or in the /Alt of the structure element that encloses it.
- 11-005 Natural language in the TU entry for form fields cannot be determinedForm field tooltips are the accessible name of the field and need a determinable language.
Other conditions in checkpoint 11
Checkpoint 11 covers declared natural language. These are its other failure conditions; the ones without a link are in the rule set but do not have a written page yet.
- 11-001 Natural language for text in page content cannot be determinedNo /Lang is in effect for some text: neither on the catalog, nor on an enclosing structure element, nor on a marked-content sequence.
- 11-002 Natural language for Alt, ActualText and E cannot be determinedAlternative text, actual text and expansion text are announced by the reader and therefore need a determinable language just as page content does.
- 11-003 Natural language in the Outline entries cannot be determinedBookmark titles have no determinable language.
- 11-005 Natural language in the TU entry for form fields cannot be determinedForm field tooltips are the accessible name of the field and need a determinable language.
- 11-006 Natural language for document metadata cannot be determinedThe XMP dc:title (and other metadata) has no xml:lang and the catalog has no /Lang.
- 11-007 Natural language is not appropriateA language is declared but it is the wrong one — a Hebrew document declared en-US, or an English abstract inside a Hebrew paper inheriting he-IL.
Check your own file. Taggart’s validator is free and unlimited — 75 of the 87 Matterhorn conditions software can decide, with the other 12 listed for you to confirm; no watermark, no expiry, and no account needed up to 60 pages.
Checked with Taggart on a generated file that fails this condition on . The Acrobat steps follow Adobe’s documentation and were not walked through by hand. Last updated .