Ctrl K
ring2all.com

Languages Module Documentation

Table of Contents

  1. Module Overview (Technical)
  2. Module Overview (Commercial/Business)
  3. Module Overview (End User/Administrator)
  4. Configuration Fields Reference
  5. Voice Guides
  6. Common Scenarios & Examples
  7. Limitations & Important Notes
  8. Troubleshooting Tips
  9. Glossary

---

1. Module Overview (Technical)

What Are Languages?

Languages (Language Overrides) allow you to set the audio prompt language for a call and route to a destination. This controls which FreeSWITCH sound files are used for prompts, IVRs, and system messages.

Architecture

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│                  Language Routing Flow                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Call enters (via IVR, inbound route, etc.)                     │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                   language.lua                           │   │
│  │                                                          │   │
│  │  1. Lookup voice guide in public.voice_guides            │   │
│  │  2. Set session language variables:                      │   │
│  │     - language = "en-us-emma"                           │   │
│  │     - sounds_language = "/usr/share/freeswitch/sounds/  │   │
│  │       en/us/emma/"                                      │   │
│  │  3. Look up destination in public.language_overrides    │   │
│  │  4. Play optional language change prompt                 │   │
│  │  5. Route to destination                                 │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  All subsequent prompts use the selected language        │   │
│  │                                                          │   │
│  │  - Welcome messages                                      │   │
│  │  - IVR prompts                                          │   │
│  │  - System messages (busy, unavailable, etc.)            │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

TablePurpose
public.voice_guidesVoice guide definitions (language/dialect/voice)
public.language_overridesLanguage override configurations

Key Files

FileDescription
admin/apps/web/src/modules/languages/Frontend module
admin/apps/web/src/i18n/en/languages.jsonTranslations
telephony/freeswitch/lua/main/xml_handlers/routing/language.luaMain handler
telephony/freeswitch/lua/resources/utils/language_utils.luaLanguage utilities
---

2. Module Overview (Commercial/Business)

Business Value

Languages enable multi-language call experiences:

Without LanguagesWith Languages
Single languageMultiple languages
US English onlySpanish, French, etc.
No voice selectionChoose voice persona
Static experienceDynamic per-caller

Use Cases

  1. Language Selection IVR

- "Press 1 for English, 2 for Spanish"

- Set language before main IVR

  1. Multi-Region Support

- Route based on caller region

- Auto-detect from SIP headers

  1. Voice Branding

- Different voice personas (Emma, Callie, Paloma)

- Consistent brand experience

  1. Department-Specific Language

- Spanish Support department

- French Sales department

Feature Highlights

FeatureBenefit
Voice GuidesMultiple voice personas
Auto-DetectionLanguage from SIP/GeoIP
Sound Path OverrideCustom prompt paths
Session-Only OptionTemporary changes
Announcement PromptNotify language change
Channel VariablesExport for sub-modules
---

3. Module Overview (End User/Administrator)

What Can You Do?

  • Create language overrides
  • Select voice guide (language/dialect/voice)
  • Configure destination after language change
  • Set optional language change prompt
  • Enable auto-detection settings
  • Configure session-only behavior

Administrator Workflow

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              Creating a Language Override                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Tab: General                                                   │
│  ├─ Name: "Spanish Support"                                    │
│  ├─ Context: lang_spanish (auto-generated)                     │
│  ├─ Sound Path Prefix: es/es/paloma                            │
│  ├─ Destination Type: IVR                                      │
│  ├─ Destination: Spanish Main Menu                             │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Tab: Language Settings                                         │
│  ├─ Fallback Sound Path: en/us/callie                          │
│  ├─ Description: "Spanish prompts for support"                 │
│  ├─ Play Language Change Prompt: [Select]                      │
│  ├─ Auto Detect Language: Off                                  │
│  ├─ Detection Source: None                                     │
│  ├─ Temporary Change Only: Off                                 │
│  ├─ Revert After Transfer: Off                                 │
│  └─ Apply to Channel Variables: ✓                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP
Standard Paths: Use format language/dialect/voice (e.g., en/us/emma).
TIP
Apply to Channel Vars: Enable to ensure IVRs use the correct prompts.
CAUTION
Fallback Path: Always set a fallback for missing audio files.

---

4. Configuration Fields Reference

General Fields

FieldDescriptionExample
NameUnique identifierSpanish Support
ContextDialplan contextlang_spanish
Sound Path PrefixVoice guide pathes/es/paloma
Destination TypeModule to route toIVR
DestinationSpecific targetSpanish Menu
EnabledOverride activeOn/Off

Language Settings

FieldDescriptionDefault
Fallback Sound PathBackup path if primary failsen/us/callie
DescriptionOptional notes-
Language Change PromptAudio to play on changeNone
Auto Detect LanguageAuto-detect from SIPOff
Detection SourceDetection methodNone
Temporary Change OnlySession-onlyOff
Revert After TransferRestore originalOff
Apply to Channel VarsExport variablesOn
Event WebhookNotification URLNone

Detection Sources

SourceDescription
NoneNo auto-detection
SIP Accept-LanguageFrom SIP INVITE header
Caller IDFrom phone number prefix
GeoIPFrom IP geographic location
---

5. Voice Guides

What Are Voice Guides?

Voice Guides define the audio prompt source for a language:

  • Language code (en, es, fr, etc.)
  • Dialect code (us, mx, es, etc.)
  • Voice name (emma, callie, paloma, etc.)

Available Voice Guides

LanguageDialectVoicePath
EnglishUSEmmaen/us/emma
EnglishUSCallieen/us/callie
SpanishMXPalomaes/mx/paloma
SpanishESPilares/es/pilar
FrenchFRFlorianefr/fr/floriane
GermanDEHansde/de/hans

Session Variables Set

VariableExample Value
languageen-us-emma
sounds_language/usr/share/freeswitch/sounds/en/us/emma/
audio_path_primary/usr/share/freeswitch/sounds/en/us/emma/
---

6. Common Scenarios & Examples

Scenario 1: Language Selection IVR

IVR: "Language Select"
DigitDestination
1lang_english
2lang_spanish
3lang_french
Language Override: "English"
SettingValue
Sound Pathen/us/emma
DestinationMain IVR

Scenario 2: Spanish Support Line

Language Override: "Spanish Support"
SettingValue
Sound Pathes/mx/paloma
Destination TypeQueue
DestinationSpanish Support Queue
Apply to Channel Vars✓

Scenario 3: Auto-Detect Language

Language Override: "Auto Language"
SettingValue
Auto Detect✓
Detection SourceSIP Accept-Language
Fallbacken/us/callie
DestinationMain IVR
---

7. Limitations & Important Notes

Technical Notes

NOTE
Path Format: Use language/dialect/voice format (lowercase).
WARNING
Missing Audio: Ensure audio files exist for the language path.
WARNING
Channel Variables: Enable "Apply to Channel Vars" for IVR integration.

Best Practices

  1. Set Fallback: Always configure a fallback path
  2. Test All Languages: Verify audio plays correctly
  3. Use Standard Paths: Follow FreeSWITCH naming conventions
  4. Enable Channel Vars: Ensure sub-modules inherit language
  5. Prompt Before Change: Play announcement to inform caller

---

8. Troubleshooting Tips

Common Issues

SymptomPossible CauseSolution
Wrong promptsPath misconfiguredCheck sound_path
No audioMissing filesVerify audio exists
IVR not using languageChannel vars not setEnable Apply to Channel Vars
Auto-detect failsNo SIP headerCheck detection source
Fallback not workingFallback path emptySet fallback sound path

Diagnostic SQL

List language overrides:

Sql
SELECT id, name, context, destination_module, destination_data, enabled
FROM public.language_overrides
WHERE domain_id = [domain_id];

List voice guides:

Sql
SELECT name, language_code, dialect_code, voice_name, sound_path, enabled
FROM public.voice_guides
WHERE enabled = TRUE;

FreeSWITCH Logs

Bash
# Check language routing
grep "language.lua" /var/log/freeswitch/freeswitch.log
grep "sounds_language" /var/log/freeswitch/freeswitch.log

---

9. Glossary

TermDefinition
Language OverrideConfiguration to set call language
Voice GuideLanguage/dialect/voice definition
Sound PathDirectory for audio prompts
Auto-DetectionAutomatic language selection
Channel VariablesFreeSWITCH session variables
FallbackBackup language path
---

Lua Script Status ✅

Already Correct

ScriptStatus
routing/language.lua✅ Uses public.voice_guides, public.language_overrides
language_utils.lua✅ Language utility functions
No Lua fixes needed!

---

Documentation last updated: January 2026
AI Assistant

👋 Hello! I'm your Ring2All documentation assistant. I can help you find information about configuring and using the Ring2All PBX platform.

How can I help you today?