diff --git a/fern/customization/turkish-language-setup.mdx b/fern/customization/turkish-language-setup.mdx new file mode 100644 index 000000000..4b7cea82b --- /dev/null +++ b/fern/customization/turkish-language-setup.mdx @@ -0,0 +1,640 @@ +--- +title: Turkish language setup +subtitle: Learn to configure voice assistants for Turkish conversations +slug: customization/turkish-language-setup +description: Set up Turkish-speaking voice AI agents with optimized STT, TTS, and language model configuration +--- + +## Overview + +Configure your voice assistant to communicate fluently in Turkish with native speech recognition, natural-sounding voices, and culturally appropriate conversation patterns. + +**In this guide, you'll learn to:** +- Set up Turkish speech recognition with the right provider and language code +- Configure native Turkish voices for natural-sounding responses +- Design Turkish system prompts with proper formality conventions +- Handle Turkish-specific challenges like special characters and agglutinative grammar + + +**Turkish Language Support:** Turkish is well-supported across major STT and TTS providers. **Deepgram**, **Google STT**, and **Azure STT** all offer dedicated Turkish language models. For voice synthesis, **Azure** provides the most natural Turkish voices with multiple speaker options. + + +## Configure Turkish speech recognition + +Set up your transcriber to accurately process Turkish speech input. + + + + 1. Navigate to **Assistants** in your [Vapi Dashboard](https://dashboard.vapi.ai/) + 2. Create a new assistant or edit an existing one + 3. In the **Transcriber** section: + - **Provider**: Select `Deepgram` (recommended for speed) or `Google` (recommended for accuracy) + - **Model**: For Deepgram, choose `Nova 2` or `Nova 3`; for Google, choose `Latest` + - **Language**: Set to `tr` (Deepgram) or `tr-TR` (Google) + 4. Click **Save** to apply the configuration + + + ```typescript + import { VapiClient } from "@vapi-ai/server-sdk"; + + const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" }); + + // Recommended: Deepgram for Turkish (fast, accurate) + const assistant = await vapi.assistants.create({ + name: "Turkish Assistant", + transcriber: { + provider: "deepgram", + model: "nova-2", + language: "tr" + } + }); + + // Alternative: Google STT for Turkish + const googleTurkish = { + provider: "google", + model: "latest", + language: "tr-TR" + }; + + // Alternative: Azure STT for Turkish + const azureTurkish = { + provider: "azure", + language: "tr-TR" + }; + ``` + + + ```python + from vapi import Vapi + import os + + client = Vapi(token=os.getenv("VAPI_API_KEY")) + + # Recommended: Deepgram for Turkish (fast, accurate) + assistant = client.assistants.create( + name="Turkish Assistant", + transcriber={ + "provider": "deepgram", + "model": "nova-2", + "language": "tr" + } + ) + + # Alternative: Google STT for Turkish + google_turkish = { + "provider": "google", + "model": "latest", + "language": "tr-TR" + } + + # Alternative: Azure STT for Turkish + azure_turkish = { + "provider": "azure", + "language": "tr-TR" + } + ``` + + + ```bash + # Recommended: Deepgram for Turkish + curl -X POST "https://api.vapi.ai/assistant" \ + -H "Authorization: Bearer $VAPI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Turkish Assistant", + "transcriber": { + "provider": "deepgram", + "model": "nova-2", + "language": "tr" + } + }' + + # Alternative: Google STT for Turkish + curl -X POST "https://api.vapi.ai/assistant" \ + -H "Authorization: Bearer $VAPI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "transcriber": { + "provider": "google", + "model": "latest", + "language": "tr-TR" + } + }' + ``` + + + + +**Multilingual with Turkish:** If your assistant needs to handle both Turkish and other languages in the same conversation, use Deepgram with `language: "multi"` or Google with `language: "multilingual"` instead. See the [multilingual support guide](/customization/multilingual) for details. + + +## Set up Turkish voices + +Configure your assistant to use native Turkish voices for natural-sounding speech output. + + + + 1. In the **Voice** section of your assistant: + - **Provider**: Select `Azure` (recommended for Turkish) + - **Voice**: Choose one of: + - `tr-TR-EmelNeural` (female, natural conversational tone) + - `tr-TR-AhmetNeural` (male, natural conversational tone) + 2. **Alternative providers**: + - **ElevenLabs**: Select a multilingual voice (supports Turkish automatically) + - **OpenAI TTS**: Use any voice (supports Turkish text natively) + 3. Click **Save** to apply the voice configuration + + + ```typescript + // Recommended: Azure with native Turkish voices + const femaleVoice = { + provider: "azure", + voiceId: "tr-TR-EmelNeural" + }; + + const maleVoice = { + provider: "azure", + voiceId: "tr-TR-AhmetNeural" + }; + + // Alternative: ElevenLabs multilingual voice + const elevenLabsVoice = { + provider: "11labs", + voiceId: "21m00Tcm4TlvDq8ikWAM", // Rachel (multilingual) + model: "eleven_multilingual_v2" + }; + + await vapi.assistants.update(assistantId, { voice: femaleVoice }); + ``` + + + ```python + # Recommended: Azure with native Turkish voices + female_voice = { + "provider": "azure", + "voiceId": "tr-TR-EmelNeural" + } + + male_voice = { + "provider": "azure", + "voiceId": "tr-TR-AhmetNeural" + } + + # Alternative: ElevenLabs multilingual voice + eleven_labs_voice = { + "provider": "11labs", + "voiceId": "21m00Tcm4TlvDq8ikWAM", # Rachel (multilingual) + "model": "eleven_multilingual_v2" + } + + client.assistants.update(assistant_id, voice=female_voice) + ``` + + + ```bash + # Azure with native Turkish female voice + curl -X PATCH "https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID" \ + -H "Authorization: Bearer $VAPI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "voice": { + "provider": "azure", + "voiceId": "tr-TR-EmelNeural" + } + }' + + # Azure with native Turkish male voice + curl -X PATCH "https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID" \ + -H "Authorization: Bearer $VAPI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "voice": { + "provider": "azure", + "voiceId": "tr-TR-AhmetNeural" + } + }' + ``` + + + + +**Voice Quality:** Azure's `tr-TR-EmelNeural` and `tr-TR-AhmetNeural` voices provide the most natural Turkish pronunciation, including correct handling of Turkish-specific sounds like soft g (ğ), undotted i (ı), and cedilla characters (ş, ç). ElevenLabs multilingual voices also produce high-quality Turkish speech. + + +## Configure Turkish system prompts + +Design system prompts that handle Turkish cultural conventions, formality levels, and conversational patterns. + +Turkish has two forms of address: **siz** (formal "you") and **sen** (informal "you"). Choose the appropriate form based on your use case. + + + + 1. In the **Model** section, set your system prompt. Here is a template for a formal Turkish assistant: + ``` + Sen Türkçe konuşan yardımcı bir asistansın. + + Dil Kuralları: + - Her zaman Türkçe yanıt ver + - "Siz" (resmi) hitap formunu kullan + - Nazik ve profesyonel bir ton kullan + - Türk kültürüne uygun selamlaşma ve nezaket kalıplarını kullan + - Kullanıcı başka bir dilde yazarsa, kibarca Türkçe konuşabildiğini belirt ve Türkçe devam etmesini iste + + Kültürel Yönergeler: + - Selamlaşmada "Merhaba", "İyi günler" veya "Hoş geldiniz" kullan + - Vedalaşmada "İyi günler", "Hoşça kalın" veya "Görüşmek üzere" kullan + - Resmi ortamlarda "Efendim" ifadesini kullan + - Sabırlı ve saygılı bir iletişim tarzı benimse + ``` + 2. Click **Save** to apply the prompt changes + + + ```typescript + // Formal Turkish assistant prompt (siz form) + const formalPrompt = `Sen Türkçe konuşan yardımcı bir asistansın. + +Dil Kuralları: +- Her zaman Türkçe yanıt ver +- "Siz" (resmi) hitap formunu kullan +- Nazik ve profesyonel bir ton kullan +- Türk kültürüne uygun selamlaşma ve nezaket kalıplarını kullan +- Kullanıcı başka bir dilde yazarsa, kibarca Türkçe konuşabildiğini belirt ve Türkçe devam etmesini iste + +Kültürel Yönergeler: +- Selamlaşmada "Merhaba", "İyi günler" veya "Hoş geldiniz" kullan +- Vedalaşmada "İyi günler", "Hoşça kalın" veya "Görüşmek üzere" kullan +- Resmi ortamlarda "Efendim" ifadesini kullan +- Sabırlı ve saygılı bir iletişim tarzı benimse`; + + // Informal Turkish assistant prompt (sen form) + const informalPrompt = `Sen Türkçe konuşan samimi bir asistansın. + +Dil Kuralları: +- Her zaman Türkçe yanıt ver +- "Sen" (samimi) hitap formunu kullan +- Sıcak ve arkadaşça bir ton kullan +- Kullanıcı başka bir dilde yazarsa, kibarca Türkçe konuşabildiğini belirt`; + + const model = { + provider: "openai", + model: "gpt-4o", + messages: [ + { + role: "system", + content: formalPrompt + } + ] + }; + + await vapi.assistants.update(assistantId, { model }); + ``` + + + ```python + # Formal Turkish assistant prompt (siz form) + formal_prompt = """Sen Türkçe konuşan yardımcı bir asistansın. + +Dil Kuralları: +- Her zaman Türkçe yanıt ver +- "Siz" (resmi) hitap formunu kullan +- Nazik ve profesyonel bir ton kullan +- Türk kültürüne uygun selamlaşma ve nezaket kalıplarını kullan +- Kullanıcı başka bir dilde yazarsa, kibarca Türkçe konuşabildiğini belirt ve Türkçe devam etmesini iste + +Kültürel Yönergeler: +- Selamlaşmada "Merhaba", "İyi günler" veya "Hoş geldiniz" kullan +- Vedalaşmada "İyi günler", "Hoşça kalın" veya "Görüşmek üzere" kullan +- Resmi ortamlarda "Efendim" ifadesini kullan +- Sabırlı ve saygılı bir iletişim tarzı benimse""" + + # Informal Turkish assistant prompt (sen form) + informal_prompt = """Sen Türkçe konuşan samimi bir asistansın. + +Dil Kuralları: +- Her zaman Türkçe yanıt ver +- "Sen" (samimi) hitap formunu kullan +- Sıcak ve arkadaşça bir ton kullan +- Kullanıcı başka bir dilde yazarsa, kibarca Türkçe konuşabildiğini belirt""" + + model = { + "provider": "openai", + "model": "gpt-4o", + "messages": [ + { + "role": "system", + "content": formal_prompt + } + ] + } + + client.assistants.update(assistant_id, model=model) + ``` + + + ```bash + curl -X PATCH "https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID" \ + -H "Authorization: Bearer $VAPI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": { + "provider": "openai", + "model": "gpt-4o", + "messages": [ + { + "role": "system", + "content": "Sen Türkçe konuşan yardımcı bir asistansın.\n\nDil Kuralları:\n- Her zaman Türkçe yanıt ver\n- \"Siz\" (resmi) hitap formunu kullan\n- Nazik ve profesyonel bir ton kullan\n- Türk kültürüne uygun selamlaşma ve nezaket kalıplarını kullan" + } + ] + } + }' + ``` + + + + +**Formality matters in Turkish:** Using the wrong formality level can come across as disrespectful (too informal in business) or distant (too formal among peers). Use **siz** for customer service, healthcare, banking, and professional contexts. Use **sen** for casual apps, gaming, or youth-oriented products. + + +## Add a Turkish greeting + +Configure a first message that sets the right tone for Turkish conversations. + + + + 1. In the **First Message** field, enter a Turkish greeting: + - **Formal**: `Merhaba, hoş geldiniz! Size nasıl yardımcı olabilirim?` + - **Informal**: `Merhaba! Sana nasıl yardımcı olabilirim?` + 2. Click **Save** to apply the greeting + + + ```typescript + // Formal Turkish greeting (siz) + const formalGreeting = "Merhaba, hoş geldiniz! Size nasıl yardımcı olabilirim?"; + + // Informal Turkish greeting (sen) + const informalGreeting = "Merhaba! Sana nasıl yardımcı olabilirim?"; + + await vapi.assistants.update(assistantId, { + firstMessage: formalGreeting + }); + ``` + + + ```python + # Formal Turkish greeting (siz) + formal_greeting = "Merhaba, hoş geldiniz! Size nasıl yardımcı olabilirim?" + + # Informal Turkish greeting (sen) + informal_greeting = "Merhaba! Sana nasıl yardımcı olabilirim?" + + client.assistants.update( + assistant_id, + first_message=formal_greeting + ) + ``` + + + ```bash + curl -X PATCH "https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID" \ + -H "Authorization: Bearer $VAPI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "firstMessage": "Merhaba, hoş geldiniz! Size nasıl yardımcı olabilirim?" + }' + ``` + + + +## Complete Turkish assistant example + +Combine all the configuration pieces into a fully functional Turkish voice assistant. + + + + ```typescript + import { VapiClient } from "@vapi-ai/server-sdk"; + + const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" }); + + const turkishAssistant = await vapi.assistants.create({ + name: "Turkish Customer Service Agent", + firstMessage: "Merhaba, hoş geldiniz! Size nasıl yardımcı olabilirim?", + transcriber: { + provider: "deepgram", + model: "nova-2", + language: "tr" + }, + model: { + provider: "openai", + model: "gpt-4o", + messages: [ + { + role: "system", + content: `Sen Türkçe konuşan bir müşteri hizmetleri temsilcisisin. + +Dil Kuralları: +- Her zaman Türkçe yanıt ver +- "Siz" (resmi) hitap formunu kullan +- Nazik ve profesyonel bir ton kullan +- Türk kültürüne uygun selamlaşma ve nezaket kalıplarını kullan + +Kültürel Yönergeler: +- Selamlaşmada "Merhaba" veya "İyi günler" kullan +- Vedalaşmada "İyi günler" veya "Hoşça kalın" kullan +- Resmi ortamlarda "Efendim" ifadesini kullan +- Sabırlı ve saygılı bir iletişim tarzı benimse + +Görevin müşterilere yardımcı olmak, sorularını yanıtlamak ve sorunlarını çözmektir.` + } + ] + }, + voice: { + provider: "azure", + voiceId: "tr-TR-EmelNeural" + } + }); + + console.log("Turkish assistant created:", turkishAssistant.id); + ``` + + + ```python + from vapi import Vapi + import os + + client = Vapi(token=os.getenv("VAPI_API_KEY")) + + turkish_assistant = client.assistants.create( + name="Turkish Customer Service Agent", + first_message="Merhaba, hoş geldiniz! Size nasıl yardımcı olabilirim?", + transcriber={ + "provider": "deepgram", + "model": "nova-2", + "language": "tr" + }, + model={ + "provider": "openai", + "model": "gpt-4o", + "messages": [ + { + "role": "system", + "content": """Sen Türkçe konuşan bir müşteri hizmetleri temsilcisisin. + +Dil Kuralları: +- Her zaman Türkçe yanıt ver +- "Siz" (resmi) hitap formunu kullan +- Nazik ve profesyonel bir ton kullan +- Türk kültürüne uygun selamlaşma ve nezaket kalıplarını kullan + +Kültürel Yönergeler: +- Selamlaşmada "Merhaba" veya "İyi günler" kullan +- Vedalaşmada "İyi günler" veya "Hoşça kalın" kullan +- Resmi ortamlarda "Efendim" ifadesini kullan +- Sabırlı ve saygılı bir iletişim tarzı benimse + +Görevin müşterilere yardımcı olmak, sorularını yanıtlamak ve sorunlarını çözmektir.""" + } + ] + }, + voice={ + "provider": "azure", + "voiceId": "tr-TR-EmelNeural" + } + ) + + print(f"Turkish assistant created: {turkish_assistant.id}") + ``` + + + ```bash + curl -X POST "https://api.vapi.ai/assistant" \ + -H "Authorization: Bearer $VAPI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Turkish Customer Service Agent", + "firstMessage": "Merhaba, hoş geldiniz! Size nasıl yardımcı olabilirim?", + "transcriber": { + "provider": "deepgram", + "model": "nova-2", + "language": "tr" + }, + "model": { + "provider": "openai", + "model": "gpt-4o", + "messages": [ + { + "role": "system", + "content": "Sen Türkçe konuşan bir müşteri hizmetleri temsilcisisin.\n\nDil Kuralları:\n- Her zaman Türkçe yanıt ver\n- \"Siz\" (resmi) hitap formunu kullan\n- Nazik ve profesyonel bir ton kullan\n- Türk kültürüne uygun selamlaşma ve nezaket kalıplarını kullan\n\nKültürel Yönergeler:\n- Selamlaşmada \"Merhaba\" veya \"İyi günler\" kullan\n- Vedalaşmada \"İyi günler\" veya \"Hoşça kalın\" kullan\n- Resmi ortamlarda \"Efendim\" ifadesini kullan\n- Sabırlı ve saygılı bir iletişim tarzı benimse\n\nGörevin müşterilere yardımcı olmak, sorularını yanıtlamak ve sorunlarını çözmektir." + } + ] + }, + "voice": { + "provider": "azure", + "voiceId": "tr-TR-EmelNeural" + } + }' + ``` + + + +## Provider capabilities for Turkish + +### Speech recognition (STT) + +| Provider | Turkish Support | Language Code | Notes | +|----------|----------------|---------------|-------| +| **Deepgram** | Yes | `tr` | **Recommended**: Nova 2/Nova 3, fast and accurate | +| **Google STT** | Yes | `tr-TR` | Latest models, strong accuracy | +| **Azure STT** | Yes | `tr-TR` | Good accuracy, single-language mode | +| **Gladia** | Yes | Auto-detected | Automatic language detection includes Turkish | +| **Speechmatics** | Yes | `tr` | Available but fewer optimizations | +| **Talkscriber** | Yes | `tr` | Basic Turkish support | +| **Assembly AI** | No | N/A | English only | + +### Voice synthesis (TTS) + +| Provider | Turkish Voices | Recommended Voice | Notes | +|----------|---------------|-------------------|-------| +| **Azure** | 2+ neural voices | `tr-TR-EmelNeural` (F), `tr-TR-AhmetNeural` (M) | **Best Turkish pronunciation** | +| **ElevenLabs** | Multilingual voices | Any multilingual v2 voice | High quality, natural prosody | +| **OpenAI TTS** | All voices | `alloy`, `nova`, `shimmer` | Supports Turkish text natively | +| **PlayHT** | Multilingual voices | Select Turkish-compatible voice | Cost-effective option | + +### Language models (LLM) + +| Provider | Turkish Support | Recommended Model | Notes | +|----------|----------------|-------------------|-------| +| **OpenAI** | Yes | `gpt-4o` | Strong Turkish comprehension and generation | +| **Anthropic** | Yes | `claude-3.5-sonnet` | Good cultural context understanding | +| **Google** | Yes | `gemini-1.5-pro` | Native multilingual capabilities | + +## Common challenges and solutions + + + + **Problem:** Turkish characters like ğ, ş, ç, ı, ö, ü, and İ are misrecognized or dropped. + + **Solutions:** + - Use Deepgram or Google STT with the Turkish language code explicitly set + - Verify your audio input quality is clear and has minimal background noise + - Test with native Turkish speakers to validate character accuracy + - In your system prompt, include example words with special characters to reinforce correct handling + + + + **Problem:** The assistant mixes siz (formal) and sen (informal) forms inconsistently. + + **Solutions:** + - Explicitly specify the required formality level in your system prompt + - Include examples of correct verb conjugations (e.g., "yapabilirsiniz" for siz, "yapabilirsin" for sen) + - Add a rule: "Her zaman siz formunu kullan, asla sen formuna geçme" (Always use siz form, never switch to sen) + - Test with multiple conversation turns to verify consistency + + + + **Problem:** The transcriber frequently misrecognizes Turkish words. + + **Solutions:** + - Switch to Deepgram Nova 2 or Nova 3 with `language: "tr"` for best results + - Ensure clear audio quality with minimal background noise + - Avoid using multilingual/auto-detect mode if the conversation is Turkish-only + - Add common domain-specific Turkish terms to your assistant's context through the system prompt + + + + **Problem:** The TTS output has awkward pronunciation or unnatural prosody. + + **Solutions:** + - Use Azure's native Turkish voices (`tr-TR-EmelNeural` or `tr-TR-AhmetNeural`) for the best results + - If using ElevenLabs, select the `eleven_multilingual_v2` model + - Keep Turkish sentences shorter in your prompts to improve pronunciation flow + - Avoid mixing Turkish and English in the same sentence where possible + + + + **Problem:** The language model sometimes falls back to English in its responses. + + **Solutions:** + - Write your entire system prompt in Turkish (not English instructions about Turkish) + - Add an explicit rule: "Her zaman Türkçe yanıt ver, asla İngilizce kullanma" + - Use GPT-4o or Claude 3.5 Sonnet for the strongest Turkish language adherence + - Set the first message in Turkish to establish the language context from the start + + + +## Best practices + +- **Write your system prompt in Turkish.** LLMs produce more natural and consistent Turkish output when the system prompt itself is in Turkish, rather than English instructions about speaking Turkish. +- **Set the language code explicitly.** For Turkish-only assistants, always set the specific Turkish language code (`tr` or `tr-TR`) rather than using multilingual auto-detection. This improves STT accuracy. +- **Choose the right formality level early.** Decide between siz (formal) and sen (informal) before writing your prompt. Mixing formality levels mid-conversation is considered poor etiquette in Turkish. +- **Test with native speakers.** Turkish pronunciation and grammar have nuances that automated testing may miss. Have native Turkish speakers validate your assistant's output. +- **Handle Turkish-specific greetings.** Use time-appropriate greetings when possible: "Günaydın" (morning), "İyi günler" (daytime), "İyi akşamlar" (evening). + +## Next steps + +Now that you have Turkish language support configured: + +- **[Multilingual support](/customization/multilingual):** Add additional languages alongside Turkish +- **[Custom voices](/customization/custom-voices/custom-voice):** Create a custom Turkish voice for your brand +- **[Prompting guide](/prompting-guide):** Design more effective Turkish conversation flows +- **[Call analysis](/call-analysis):** Monitor Turkish call quality and performance diff --git a/fern/docs.yml b/fern/docs.yml index 7ba3888c4..1c5632b28 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -140,6 +140,8 @@ navigation: path: assistants/dynamic-variables.mdx - page: Multilingual support path: customization/multilingual.mdx + - page: Turkish language setup + path: customization/turkish-language-setup.mdx - page: Personalization with user information path: assistants/personalization.mdx - page: Voice formatting plan