> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kugelaudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Text Normalization

> SDK reference for text normalization: turn numbers, dates and symbols into spoken words with the normalize and language options, and spell out text with tags.

Text normalization converts numbers, dates, times, and other non-verbal text
into spoken words (for example "3 apples" becomes "three apples"). It is on by
default. How it works, the supported languages and their codes are documented in
[Text processing](/features/text-processing). The SDKs control it with the
`normalize` and `language` options:

<CodeGroup>

```python Python
# With explicit language (recommended)
audio = client.tts.generate(
    text="I bought 3 items for €50.99 on 01/15/2024.",
    voice_id=1071,
    normalize=True,
    language="en",
)

# Without language: normalized in the language the text is written in
audio = client.tts.generate(
    text="Ich habe 3 Artikel für 50,99€ gekauft.",
    voice_id=1071,
    normalize=True,
    # language not specified: recognized from the text (here German)
)
```

```typescript TypeScript
// With explicit language (recommended)
const audio = await client.tts.generate({
  text: 'I bought 3 items for €50.99 on 01/15/2024.',
  voiceId: 1071,
  normalize: true,
  language: 'en',
});

// Without language: normalized in the language the text is written in
const voiceLanguageAudio = await client.tts.generate({
  text: 'Ich habe 3 Artikel für 50,99€ gekauft.',
  voiceId: 1071,
  normalize: true,
  // language not specified: recognized from the text (here German)
});
```

```java Java
// With explicit language (recommended)
AudioResponse audio = client.tts().generate(
    GenerateRequest.builder("I bought 3 items for €50.99 on 01/15/2024.")
        .voiceId(1071)
        .normalize(true)
        .language("en")
        .build()
);

// Without language: normalized in the language the text is written in
AudioResponse voiceLanguageAudio = client.tts().generate(
    GenerateRequest.builder("Ich habe 3 Artikel für 50,99€ gekauft.")
        .voiceId(1071)
        .normalize(true)
        // language not specified: recognized from the text (here German)
        .build()
);
```

```rust Rust
// With explicit language (recommended)
let audio = client
    .tts()
    .generate(
        &TtsRequest::new("I bought 3 items for €50.99 on 01/15/2024.")
            .voice_id(1071)
            .normalize(true)
            .language("en"),
    )
    .await?;

// Without language: normalized in the language the text is written in
let voice_language_audio = client
    .tts()
    .generate(
        &TtsRequest::new("Ich habe 3 Artikel für 50,99€ gekauft.")
            .voice_id(1071)
            .normalize(true), // language not specified: recognized from the text (here German)
    )
    .await?;
```

```cpp C++
// With explicit language (recommended)
kugelaudio::GenerateRequest request;
request.text = "I bought 3 items for €50.99 on 01/15/2024.";
request.voice_id = 1071;
request.normalize = true;
request.language = "en";
kugelaudio::AudioResponse audio = client.tts().generate(request);

// Without language: normalized in the language the text is written in
kugelaudio::GenerateRequest voice_language_request;
voice_language_request.text = "Ich habe 3 Artikel für 50,99€ gekauft.";
voice_language_request.voice_id = 1071;
voice_language_request.normalize = true;
// language not specified: recognized from the text (here German)
kugelaudio::AudioResponse voice_language_audio = client.tts().generate(voice_language_request);
```

```dart Dart
// With explicit language (recommended)
final audio = await client.tts.generate(
  text: 'I bought 3 items for €50.99 on 01/15/2024.',
  voiceId: 1071,
  normalize: true,
  language: 'en',
);

// Without language: normalized in the language the text is written in
final voiceLanguageAudio = await client.tts.generate(
  text: 'Ich habe 3 Artikel für 50,99€ gekauft.',
  voiceId: 1071,
  normalize: true,
  // language not specified: recognized from the text (here German)
);
```

</CodeGroup>

Without a language, the Rust, C++ and Dart SDKs log a warning when normalization
is on.

<Warning>
  Normalizing without a language may cause incorrect normalizations, especially for
  short texts or languages that share similar vocabulary. Always set the language
  when you know it.
</Warning>

## Spell tags

Wrap text in `<spell>` tags to have it read character by character (emails,
codes, acronyms). Tag semantics and per-language character names are in
[Spell tags](/prompting/spell). In a streaming session, a tag split across
tokens is handled for you:

<CodeGroup>

```python Python
async with client.tts.streaming_session(
    voice_id=1071,
    normalize=True,
    language="en",
) as session:
    async for chunk in session.send("My code is <spell>"):
        play_audio(chunk.audio)
    async for chunk in session.send("ABC123</spell>"):
        play_audio(chunk.audio)
    async for chunk in session.flush():
        play_audio(chunk.audio)
```

```typescript TypeScript
const session = client.tts.streamingSession(
  { voiceId: 1071, normalize: true, language: 'en' },
  { onChunk: (chunk) => playAudio(chunk.audio) },
);
await session.connect();

session.send('My code is <spell>');
session.send('ABC123</spell>');

await session.close();
```

```java Java
StreamConfig config = StreamConfig.builder()
    .voiceId(1071)
    .normalize(true)
    .language("en")
    .build();

try (StreamingSession session = client.streamingSession(config, chunk -> playAudio(chunk.getAudio()))) {
    session.send("My code is <spell>");
    session.send("ABC123</spell>");
}
```

```rust Rust
use futures_util::StreamExt;
use kugelaudio::StreamConfig;

let mut session = client
    .tts()
    .streaming_session(StreamConfig::new(1071).normalize(true).language("en"));

for text in ["My code is <spell>", "ABC123</spell>"] {
    let mut audio = session.send(text, false);
    while let Some(chunk) = audio.next().await {
        play_audio(&chunk?.audio);
    }
}
let mut tail = session.flush();
while let Some(chunk) = tail.next().await {
    play_audio(&chunk?.audio);
}
drop(tail);
session.close().await?;
```

```cpp C++
kugelaudio::StreamConfig config;
config.voice_id = 1071;
config.normalize = true;
config.language = "en";

auto play_chunk = [](const kugelaudio::AudioChunk& chunk) { play_audio(chunk.audio); };
kugelaudio::StreamingSession session = client.tts().streaming_session(config);
session.send("My code is <spell>", /*flush=*/false, play_chunk);
session.send("ABC123</spell>", /*flush=*/false, play_chunk);
session.flush(play_chunk);
session.close();
```

```dart Dart
final session = client.tts.streamingSession(
  StreamConfig(voiceId: 1071, normalize: true, language: 'en'),
);
session.audio.listen((chunk) => playAudio(chunk.audio));

await session.send('My code is <spell>');
await session.send('ABC123</spell>');
await session.flush();
await session.close();
```

</CodeGroup>

`play_audio` / `playAudio` stands for your own playback function.

## Next steps

- [Dictionaries](/sdks/dictionaries): per-project pronunciation and replacement lists
- [Generate speech](/sdks/generate): generation parameters including `normalize` and `language`
