Number Translation

📖 Back to Main Documentation

Number translation converts phone numbers between different formats to ensure consistent E.164 formatting throughout the system.

Related Documentation

Core Documentation

• 📋 Main README - Overview and quick start
• 🔧 Configuration Guide - Number translation configuration (number_translate)
• 🔧 Operations Guide - Number translation testing in Control Panel

Call Processing Flow

• 🔀 Dialplan Configuration - Using translated numbers in dialplan (translation happens first)
• 👥 Sh Interface - Sh lookup uses translated numbers
• 💳 Online Charging - OCS receives translated numbers
• 📡 SS7 MAP - HLR queries use translated numbers

Related Services

• ⚙️ Supplementary Services - CLI blocking prefix stripping during translation
• 📞 Voicemail - Voicemail numbers in translation

Monitoring

• 📊 Metrics Reference - Number translation metrics

---

Number Translation

Number translation converts phone numbers between different formats (local, national, international) to ensure consistent E.164 formatting throughout the system.

What is Number Translation?

Number translation normalizes phone numbers to E.164 format (international standard) before call processing. This ensures:

• Consistent numbering throughout the system
• Proper routing to on-net and off-net destinations
• Compatibility with international SIP trunks and IMS networks

E.164 Format: [Country Code][National Number] (no + prefix, no spaces)

• Example: 61403123456 (Australia mobile)
• Example: 16505551234 (US number)

When Translation Occurs

Translation happens:

• Before Sh lookups
• Before HLR lookups
• Before OCS authorization
• Before dialplan XML is generated

For MT Calls: Translate destination number (called party) For MO Calls: Translate both source and destination numbers

Configuration

config :tas,
  number_translate: %{
    country_code: :PF,        # ISO 3166-1 alpha-2 country code
    localAreaCode: "617"      # Default area code for short numbers
  }

Parameters:

• country_code: ISO country code as atom (e.g., :AU, :US, :PF)
• localAreaCode: Area code prepended to short local numbers

Supported Country Codes

The TAS includes translation logic for these countries:

Country Code	Country	Supported Formats	E.164 Prefix
:AU	Australia	0NSN (10-digit), SN (8-digit), E.164	61
:US	United States	NPANXXXXXX (10-digit), 1+NPANXXXXXX, E.164	1
:PF	French Polynesia	Local (6-digit), National (8-digit), E.164	689

Adding New Country Codes: Country-specific translation logic must be implemented in lib/numbertranslation.ex. Contact your integration engineer to add new countries.

Special Translation Behaviors

1. CLI Blocking Prefix Stripping

Before format translation, CLI blocking prefixes are removed:

Input:  *67555123456
Step 1: Strip *67 → 555123456
Step 2: Translate → 1555123456 (if US)

2. SIP Parameter Stripping

Parameters after semicolons are removed:

Input:  61403123456;npdi;rn=+61400000000
Step 1: Strip ;npdi;rn=... → 61403123456
Step 2: Translate → 61403123456

3. Non-Digit Character Removal

All non-digit characters (except +) are stripped:

Input:  +61 (403) 123-456
Step 1: Strip formatting → +61403123456
Step 2: Translate → 61403123456

Variables Set After Translation

Variable	Value	Description
destination_number	E.164 format	Normalized destination number
tas_destination_number	E.164 format	Same as destination_number (both set for compatibility)
effective_caller_id_number	E.164 format	Normalized source number (MO calls)

What Happens When Translation Fails

Scenario: Undefined Country Code

config :tas, number_translate: %{country_code: :XX}  # Invalid

Result: {:error, "Undefined Country Code"} - call rejected

Scenario: Invalid Number Format

Input: "abc123" (contains letters)
Step 1: Strip non-digits → "123"
Step 2: Too short, cannot match any pattern
Result: May pass through as-is or reject based on dialplan logic

Best Practice: Always validate subscriber provisioning with correct E.164 numbers in HSS.

Testing Number Translation

Web UI Translation Tester (/translate):

1. Navigate to /translate in Control Panel
2. Select country code from dropdown
3. Enter test number in any format
4. View translated E.164 output
5. Test multiple formats to validate

Common Test Scenarios:

• Local short codes → E.164
• National format (0NSN) → E.164
• International format (+CC) → E.164
• Numbers with CLI prefixes → stripped and translated
• Numbers with formatting (spaces, dashes) → clean E.164

Troubleshooting Number Translation

Problem: Calls failing with "UNALLOCATED_NUMBER"

1. Check translated number format:

   • Use /translate tool to test number
   • Verify output matches expected E.164 format
   • Confirm country code and area code are correct

2. Check Sh lookup:

   • Translated number is used for Sh query
   • Use /sh_test with translated number
   • Verify subscriber exists with that MSISDN

3. Check dialplan variables:

   • Review logs for destination_number value
   • Confirm translation occurred before dialplan

Problem: Wrong area code applied

# Configuration
config :tas, number_translate: %{
  country_code: :AU,
  localAreaCode: "617"  # Wrong for your region
}

# Input: 12345678 (8-digit local)
# Output: 6161712345678 (incorrect - double area code)
# Fix: Set correct localAreaCode for your deployment

Problem: International numbers not recognized

Check if number includes country code:

• ✅ +61403123456 or 61403123456 → Recognized
• ❌ 0403123456 in wrong country_code config → Misrouted

MO vs MT Translation Behavior

MT (Mobile Terminated) Calls:

• Only destination number (called party) is translated
• Source number (caller) passed through as-is from SIP
• Destination used for Sh lookup of called subscriber

MO (Mobile Originating) Calls:

• Destination number (called party) translated
• Source number (calling party) also translated
• Source used for Sh lookup of calling subscriber
• Both numbers normalized for consistent logging/CDR

Best Practices

1. Use Correct Country Code:

   • Set country_code to match your deployment region
   • Test thoroughly before production

2. Configure Appropriate Local Area Code:

   • localAreaCode should match your network's default area
   • Used for short numbers without area code

3. Test All Number Formats:

   • Local (short codes)
   • National (0NSN format)
   • International (+CC format)
   • Special service numbers (emergency, voicemail)

4. Monitor Translation Logs:

   • Check for "Undefined Country Code" errors
   • Watch for unexpected number formats
   • Validate E.164 output matches expectations

5. Document Your Numbering Plan:

   • Define which formats subscribers will use
   • Test each format in /translate tool
   • Train operations staff on expected formats