Creates a new LangElement instance.
The language or locale code for the content within this element. Must be a valid BCP-47 language tag format. Common formats: - Language only: 'en', 'es', 'fr', 'de', 'zh' - Language-Region: 'en-US', 'en-GB', 'es-ES', 'es-MX', 'fr-FR', 'zh-CN' The language code determines pronunciation rules and voice characteristics.
Adds an SSML element as a child of this language element.
This allows for complex nested structures where other SSML elements (like emphasis, prosody, break, etc.) can be used within the language context. The child element inherits the language setting of this lang element.
An SSML element to add as a child. Can be any SSML element except speak, voice, or mstts:backgroundaudio [[11]].
This LangElement instance for method chaining
// Add emphasis within language context
const lang = new LangElement('es-ES');
const emphasis = new EmphasisElement('importante', 'strong');
lang
.text('Esto es ')
.addElement(emphasis);
// Add break within language
const french = new LangElement('fr-FR');
const pause = new BreakElement({ time: '500ms' });
french
.text('Bonjour')
.addElement(pause)
.text('mes amis');
// Complex nested structure
const german = new LangElement('de-DE');
const prosody = new ProsodyElement('langsam', { rate: 'slow' });
german
.text('Sprechen Sie ')
.addElement(prosody)
.text(' bitte');
ProtectedescapeProtectedEscapes special XML characters in text content to ensure valid XML output.
This method replaces XML special characters with their corresponding entity references to prevent XML parsing errors and potential security issues (XML injection). It should be used whenever inserting user-provided or dynamic text content into XML elements.
The following characters are escaped:
& becomes & (must be escaped first to avoid double-escaping)< becomes < (prevents opening of unintended tags)> becomes > (prevents closing of unintended tags)" becomes " (prevents breaking out of attribute values)' becomes ' (prevents breaking out of attribute values)This method is marked as protected so it's only accessible to classes that extend
SSMLElement, ensuring proper encapsulation while allowing all element implementations
to use this essential functionality.
The text content to escape
The text with all special XML characters properly escaped
// In a render method implementation
class TextElement extends SSMLElement {
private text: string = 'Hello & "world" <script>';
render(): string {
// Escapes to: Hello & "world" <script>
return `<text>${this.escapeXml(this.text)}</text>`;
}
}
// Edge cases handled correctly
this.escapeXml('5 < 10 & 10 > 5');
// Returns: '5 < 10 & 10 > 5'
this.escapeXml('She said "Hello"');
// Returns: 'She said "Hello"'
this.escapeXml("It's a test");
// Returns: 'It's a test'
// Prevents XML injection
this.escapeXml('</voice><voice name="evil">');
// Returns: '</voice><voice name="evil">'
Renders the language element as an SSML XML string.
Generates the <lang> element with the xml:lang attribute specifying the language.
All content (text and child elements) is rendered within the lang tags.
Text content is automatically escaped to prevent XML injection and ensure valid output.
The XML string representation of the language element in the format:
<lang xml:lang="language-code">content</lang>
// Simple text content
const lang1 = new LangElement('es-ES');
lang1.text('Hola mundo');
console.log(lang1.render());
// Output: <lang xml:lang="es-ES">Hola mundo</lang>
// Mixed content with elements
const lang2 = new LangElement('fr-FR');
lang2
.text('Ceci est ')
.addElement(new EmphasisElement('important', 'strong'));
console.log(lang2.render());
// Output: <lang xml:lang="fr-FR">Ceci est <emphasis level="strong">important</emphasis></lang>
// Multiple text segments
const lang3 = new LangElement('de-DE');
lang3.text('Guten ').text('Tag');
console.log(lang3.render());
// Output: <lang xml:lang="de-DE">Guten Tag</lang>
// With escaped special characters
const lang4 = new LangElement('en-GB');
lang4.text('Fish & chips');
console.log(lang4.render());
// Output: <lang xml:lang="en-GB">Fish & chips</lang>
Adds plain text content to the language element.
The text will be spoken using the pronunciation rules of the specified language. Special XML characters (&, <, >, ", ') are automatically escaped to ensure valid XML output and prevent injection attacks.
The text content to add in the specified language. Will be pronounced according to the language's phonetic rules.
This LangElement instance for method chaining
// Single text segment
const lang = new LangElement('es-ES');
lang.text('Buenos días');
// Multiple text segments
const multilang = new LangElement('fr-FR');
multilang
.text('Bonjour, ')
.text('comment allez-vous?');
// With special characters (automatically escaped)
const special = new LangElement('de-DE');
special.text('Müller & Schmidt GmbH');
SSML element for specifying language changes within speech content.
The
<lang>element allows you to switch languages or locales within the synthesized speech. This is essential for multilingual content, proper pronunciation of foreign words, or when you need to include phrases from different languages within the same voice output. The element ensures that text is pronounced according to the rules of the specified language.The lang element can be nested within voice, paragraph, sentence, and most other container elements. It inherits the voice characteristics but applies language-specific pronunciation rules to its content.
Example
Remarks
See