> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sully.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Multi-Language Support
> Handle international and multilingual clinical encounters with 50+ languages and 89 BCP47 tags
## Overview
Sully.ai supports transcription and note generation in over 50 languages (**89** accepted [BCP47](https://en.wikipedia.org/wiki/IETF_language_tag) tags — see [Supported Languages](/api-reference/audio-transcriptions/languages)), enabling healthcare providers to document clinical encounters in the patient's preferred language. The API offers two modes for language handling:
| Mode | Best For | Behavior |
| ------------------- | ---------------------------- | ---------------------------------------------- |
| **Single-Language** | Known language encounters | Audio in other languages is filtered out |
| **Multilingual** | Mixed-language conversations | Automatic language detection and transcription |
Generated clinical notes are produced in the same language as the transcript, ensuring consistency throughout the documentation workflow.
***
## Supported Languages
The full list of accepted BCP47 tags is maintained in [Supported Languages](/api-reference/audio-transcriptions/languages). Highlights:
| Language | BCP47 Tags |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Arabic | `ar`, `ar-AE`, `ar-SA`, `ar-QA`, `ar-KW`, `ar-SY`, `ar-LB`, `ar-PS`, `ar-JO`, `ar-EG`, `ar-SD`, `ar-TD`, `ar-MA`, `ar-DZ`, `ar-TN`, `ar-IQ`, `ar-IR` |
| Belarusian | `be` |
| Bengali | `bn` |
| Bosnian | `bs` |
| Bulgarian | `bg` |
| Catalan | `ca` |
| Chinese (Mandarin, Simplified) | `zh`, `zh-CN`, `zh-Hans` |
| Chinese (Mandarin, Traditional) | `zh-TW`, `zh-Hant` |
| Chinese (Cantonese, Traditional) | `zh-HK` |
| Croatian | `hr` |
| Czech | `cs` |
| Danish | `da`, `da-DK` |
| Dutch | `nl` |
| English | `en`, `en-US`, `en-CA`, `en-IE`, `en-AU`, `en-GB`, `en-NZ`, `en-IN` |
| Estonian | `et` |
| Finnish | `fi` |
| Flemish | `nl-BE` |
| French | `fr`, `fr-CA` |
| German | `de`, `de-CH` |
| Greek | `el` |
| Gujarati | `gu`, `gu-IN` |
| Hebrew | `he` |
| Hindi | `hi` |
| Hungarian | `hu` |
| Indonesian | `id` |
| Italian | `it` |
| Japanese | `ja` |
| Kannada | `kn` |
| Korean | `ko`, `ko-KR` |
| Latvian | `lv` |
| Lithuanian | `lt` |
| Macedonian | `mk` |
| Malay | `ms` |
| Marathi | `mr` |
| Norwegian | `no` |
| Persian | `fa` |
| Polish | `pl` |
| Portuguese | `pt`, `pt-BR`, `pt-PT` |
| Romanian | `ro` |
| Russian | `ru` |
| Serbian | `sr` |
| Slovak | `sk` |
| Slovenian | `sl` |
| Spanish | `es`, `es-419` |
| Swedish | `sv`, `sv-SE` |
| Tagalog | `tl` |
| Tamil | `ta` |
| Telugu | `te` |
| Thai | `th`, `th-TH` |
| Turkish | `tr` |
| Ukrainian | `uk` |
| Urdu | `ur` |
| Vietnamese | `vi` |
***
## Single-Language Mode
When you know the language of the clinical encounter in advance, specify it explicitly. This improves transcription accuracy and filters out audio in other languages.
### File Upload
Specify the language when uploading audio files:
```typescript TypeScript theme={null}
import SullyAI from '@sullyai/sullyai';
import * as fs from 'fs';
const client = new SullyAI();
// Transcribe Spanish audio
const transcription = await client.audio.transcriptions.create({
audio: fs.createReadStream('patient-visit.mp3'),
language: 'es',
});
console.log(`Transcription ID: ${transcription.transcriptionId}`);
```
```python Python theme={null}
from sullyai import SullyAI
client = SullyAI()
# Transcribe Spanish audio
with open("patient-visit.mp3", "rb") as audio_file:
transcription = client.audio.transcriptions.create(
audio=audio_file,
language="es"
)
print(f"Transcription ID: {transcription.transcription_id}")
```
```bash HTTP theme={null}
curl -X POST "https://api.sully.ai/v2/audio/transcriptions" \
-H "X-API-Key: ${SULLY_API_KEY}" \
-H "X-Account-Id: ${SULLY_ACCOUNT_ID}" \
-F "audio=@./patient-visit.mp3" \
-F "language=es"
```
### Regional Variants
Use regional variants when relevant for better accuracy with regional accents and terminology:
```typescript TypeScript theme={null}
// British English
const transcription = await client.audio.transcriptions.create({
audio: fs.createReadStream('uk-patient-visit.mp3'),
language: 'en-GB',
});
// Brazilian Portuguese
const transcriptionBR = await client.audio.transcriptions.create({
audio: fs.createReadStream('brazil-patient-visit.mp3'),
language: 'pt-BR',
});
// Canadian French
const transcriptionCA = await client.audio.transcriptions.create({
audio: fs.createReadStream('quebec-patient-visit.mp3'),
language: 'fr-CA',
});
```
```python Python theme={null}
# British English
transcription = client.audio.transcriptions.create(
audio=open("uk-patient-visit.mp3", "rb"),
language="en-GB"
)
# Brazilian Portuguese
transcription_br = client.audio.transcriptions.create(
audio=open("brazil-patient-visit.mp3", "rb"),
language="pt-BR"
)
# Canadian French
transcription_ca = client.audio.transcriptions.create(
audio=open("quebec-patient-visit.mp3", "rb"),
language="fr-CA"
)
```
```bash HTTP theme={null}
# British English
curl -X POST "https://api.sully.ai/v2/audio/transcriptions" \
-H "X-API-Key: ${SULLY_API_KEY}" \
-H "X-Account-Id: ${SULLY_ACCOUNT_ID}" \
-F "audio=@./uk-patient-visit.mp3" \
-F "language=en-GB"
# Brazilian Portuguese
curl -X POST "https://api.sully.ai/v2/audio/transcriptions" \
-H "X-API-Key: ${SULLY_API_KEY}" \
-H "X-Account-Id: ${SULLY_ACCOUNT_ID}" \
-F "audio=@./brazil-patient-visit.mp3" \
-F "language=pt-BR"
```
When a specific language is set, audio in other languages will be filtered out or ignored. This is useful for ensuring clean transcripts when the encounter language is known.
***
## Multilingual Mode
For clinical encounters where multiple languages are spoken (such as with an interpreter or bilingual patients), use multilingual mode with `language=multi`.
### When to Use Multilingual Mode
* Patient and provider speak different languages
* Interpreter-assisted visits
* Bilingual patients who switch between languages
* Family members speaking different languages during the visit
### Supported Languages for Multilingual Mode
Multilingual mode works well with the following languages (pass `multi`, or any of these base tags — they route to the same multilingual code-switching behavior):
* Dutch (`nl`)
* French (`fr`)
* German (`de`)
* Hindi (`hi`)
* Italian (`it`)
* Japanese (`ja`)
* Portuguese (`pt`)
* Russian (`ru`)
* Spanish (`es`)
Use a regional tag (for example `es-419`) when you need Spanish without automatic multilingual routing. See [Supported Languages](/api-reference/audio-transcriptions/languages#automatic-multilingual-routing).
### File Upload with Multilingual Mode
```typescript TypeScript theme={null}
import SullyAI from '@sullyai/sullyai';
import * as fs from 'fs';
const client = new SullyAI();
// Transcribe a multilingual encounter
const transcription = await client.audio.transcriptions.create({
audio: fs.createReadStream('interpreter-visit.mp3'),
language: 'multi',
});
console.log(`Transcription ID: ${transcription.transcriptionId}`);
// Poll for completion
let result = await client.audio.transcriptions.retrieve(
transcription.transcriptionId
);
while (result.status === 'STATUS_PROCESSING') {
await new Promise((resolve) => setTimeout(resolve, 2000));
result = await client.audio.transcriptions.retrieve(
transcription.transcriptionId
);
}
// Transcript includes all detected languages
console.log('Multilingual Transcript:', result.payload?.transcription);
```
```python Python theme={null}
import time
from sullyai import SullyAI
client = SullyAI()
# Transcribe a multilingual encounter
with open("interpreter-visit.mp3", "rb") as audio_file:
transcription = client.audio.transcriptions.create(
audio=audio_file,
language="multi"
)
print(f"Transcription ID: {transcription.transcription_id}")
# Poll for completion
while True:
result = client.audio.transcriptions.retrieve(transcription.transcription_id)
if result.status == "STATUS_SUCCEEDED":
# Transcript includes all detected languages
print(f"Multilingual Transcript: {result.payload.transcription}")
break
elif result.status == "STATUS_ERROR":
raise Exception("Transcription failed")
time.sleep(2)
```
```bash HTTP theme={null}
# Upload with multilingual mode
curl -X POST "https://api.sully.ai/v2/audio/transcriptions" \
-H "X-API-Key: ${SULLY_API_KEY}" \
-H "X-Account-Id: ${SULLY_ACCOUNT_ID}" \
-F "audio=@./interpreter-visit.mp3" \
-F "language=multi"
# Response: { "data": { "transcriptionId": "tr_abc123" } }
# Poll for completion
curl -X GET "https://api.sully.ai/v2/audio/transcriptions/tr_abc123" \
-H "X-API-Key: ${SULLY_API_KEY}" \
-H "X-Account-Id: ${SULLY_ACCOUNT_ID}"
```
***
## Language in Streaming
When using real-time WebSocket streaming, specify the language as a URL parameter.
### WebSocket URL Parameters
```
wss://api.sully.ai/v1/audio/transcriptions/stream?sample_rate=16000&account_id={id}&api_token={token}&language={language}
```
### Single Language Streaming
```typescript TypeScript theme={null}
// Get streaming token first
const token = await getStreamingToken();
const accountId = process.env.SULLY_ACCOUNT_ID!;
// Connect with Spanish language
const ws = new WebSocket(
`wss://api.sully.ai/v1/audio/transcriptions/stream?sample_rate=16000&account_id=${accountId}&api_token=${token}&language=es`
);
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.text) {
console.log('Spanish transcript:', data.text);
}
};
```
```python Python theme={null}
import asyncio
import websockets
import json
async def stream_spanish():
token = await get_streaming_token()
account_id = os.environ["SULLY_ACCOUNT_ID"]
# Connect with Spanish language
url = f"wss://api.sully.ai/v1/audio/transcriptions/stream?sample_rate=16000&account_id={account_id}&api_token={token}&language=es"
async with websockets.connect(url) as ws:
async for message in ws:
data = json.loads(message)
if "text" in data:
print(f"Spanish transcript: {data['text']}")
asyncio.run(stream_spanish())
```
```bash HTTP theme={null}
# WebSocket URL for Spanish streaming
wss://api.sully.ai/v1/audio/transcriptions/stream?sample_rate=16000&account_id={ACCOUNT_ID}&api_token={TOKEN}&language=es
# With regional variant (British English)
wss://api.sully.ai/v1/audio/transcriptions/stream?sample_rate=16000&account_id={ACCOUNT_ID}&api_token={TOKEN}&language=en-GB
```
### Multilingual Streaming
```typescript TypeScript theme={null}
// Connect with multilingual mode
const ws = new WebSocket(
`wss://api.sully.ai/v1/audio/transcriptions/stream?sample_rate=16000&account_id=${accountId}&api_token=${token}&language=multi`
);
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.text) {
// Automatically handles multiple languages
console.log('Transcript:', data.text);
}
};
```
```python Python theme={null}
async def stream_multilingual():
token = await get_streaming_token()
account_id = os.environ["SULLY_ACCOUNT_ID"]
# Connect with multilingual mode
url = f"wss://api.sully.ai/v1/audio/transcriptions/stream?sample_rate=16000&account_id={account_id}&api_token={token}&language=multi"
async with websockets.connect(url) as ws:
async for message in ws:
data = json.loads(message)
if "text" in data:
# Automatically handles multiple languages
print(f"Transcript: {data['text']}")
asyncio.run(stream_multilingual())
```
```bash HTTP theme={null}
# WebSocket URL for multilingual streaming
wss://api.sully.ai/v1/audio/transcriptions/stream?sample_rate=16000&account_id={ACCOUNT_ID}&api_token={TOKEN}&language=multi
```
***
## Best Practices
Follow these guidelines to optimize language handling in your integration:
### Use Specific Languages When Known
When you know the language of the encounter in advance, always specify it explicitly rather than using multilingual mode. Single-language mode provides:
* Better transcription accuracy
* Faster processing
* Reduced false positives from background noise in other languages
### Use Regional Variants When Relevant
Regional variants improve accuracy for:
* **Accents**: `en-GB` for British accents, `en-AU` for Australian
* **Medical terminology**: Regional differences in drug names and procedures
* **Spelling conventions**: `en-US` vs `en-GB` spelling in generated notes
### Reserve Multilingual Mode for True Multilingual Encounters
Only use `language=multi` when the conversation genuinely involves multiple languages:
* Interpreter-assisted visits
* Bilingual patient-provider conversations
* Family discussions involving multiple languages
Using multilingual mode when only one language is spoken may reduce transcription accuracy. Always prefer single-language mode when the encounter language is known.
### Note Language Consistency
Generated clinical notes are produced in the same language as the transcript:
* Spanish transcript produces Spanish notes
* Multilingual transcripts produce notes in the dominant language of the conversation
* No separate language parameter is needed for note generation
***
## Next Steps
Learn about file upload and real-time streaming options
Generate structured notes from multilingual transcripts
Full SDK reference for Node.js applications
Full SDK reference for Python applications