SetStructElemLang

Tagged PDF & Accessibility

Description

Sets the /Lang entry on the structure element currently being built on the tag stack. The language tag overrides the document-level language for this element and all its descendants, allowing mixed-language documents to declare the correct natural language for each span of content.

Syntax

Delphi

function TPDFlib.SetStructElemLang(const Lang: WideString): Integer;

ActiveX

Function PDFlib::SetStructElemLang(Lang As String) As Long

DLL

int DLSetStructElemLang(int InstanceID, const wchar_t *Lang);
int DLSetStructElemLangA(int InstanceID, const char *Lang);

Parameters

Lang	A BCP 47 language tag string, such as `en-US`, `fr`, `de-CH`, or `zh-Hant-TW`. Pass an empty string to clear a previously set value and inherit the document-level language.

Return value

Returns 1 on success, 0 if no structure element is currently open or no document is selected.

Remarks

Call this function immediately after BeginTag or BeginTagEx while the target element is at the top of the tag stack. It is equivalent to passing a non-empty Lang argument to BeginTagEx, but may be more convenient when the language is determined separately from the element type.

The element-level /Lang entry is defined in ISO 32000-1 §14.9.2. It applies to the structure element and, by inheritance, to all child elements that do not themselves declare a /Lang. Screen readers use this entry to select the appropriate text-to-speech voice or language engine when reading the document aloud.

PDF/UA-1 (ISO 14289-1 §7.3) requires that all natural language content be identified. The document-level /Lang set by SetDocumentLanguage or SetPDFUAMode covers the primary language; SetStructElemLang covers sections whose language differs from the primary.

Example

// A French phrase embedded in an English document
PDFlib.SetPDFUAMode('en-US');
// ... English content ...
PDFlib.BeginTag('P', '', '');
PDFlib.SetStructElemLang('fr');
PDFlib.TextOut(x, y, 'Bonjour le monde');
PDFlib.EndTag;