Skip to main content

Number Translation

๐Ÿ“– Back to Main Documentation

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

Core Documentationโ€‹

Call Processing Flowโ€‹

Monitoringโ€‹

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 248 countries and territories, covering all ISO 3166-1 alpha-2 codes with telephone service.

CodeCountry/TerritoryE.164 PrefixNational LengthTrunkIDDNotes
:ACAscension Island2475None00
:ADAndorra3766-9None00
:AEUnited Arab Emirates9719000
:AFAfghanistan939000
:AGAntigua and Barbuda110None011NANP, delegates to US
:AIAnguilla110None011NANP, delegates to US
:ALAlbania3559000
:AMArmenia3748000
:AOAngola2449None00
:ARArgentina5410000
:ASAmerican Samoa110None011NANP, delegates to US
:ATAustria4310-13000
:AUAustralia61900011
:AWAruba2977None00
:AXAland Islands3589-10000Delegates to FI
:AZAzerbaijan9949000
:BABosnia and Herzegovina3878000
:BBBarbados110None011NANP, delegates to US
:BDBangladesh88010000
:BEBelgium328-9000
:BFBurkina Faso2268None00
:BGBulgaria3599000
:BHBahrain9738None00
:BIBurundi2578None00
:BJBenin2298None00
:BLSaint Barthelemy5909000
:BMBermuda110None011NANP, delegates to US
:BNBrunei6737None00
:BOBolivia5918None00
:BQBonaire/Sint Eustatius/Saba5997None00
:BRBrazil5510-11000
:BSBahamas110None011NANP, delegates to US
:BTBhutan9758None00
:BVBouvet Island478None00Delegates to NO
:BWBotswana2678None00
:BYBelarus37598810
:BZBelize5017None00
:CACanada110None011NANP, delegates to US
:CCCocos Islands61900011Delegates to AU
:CDDR Congo2439000
:CFCentral African Republic2368None00
:CGRepublic of Congo2429None00
:CHSwitzerland419000
:CIIvory Coast22510None00
:CKCook Islands6825None00
:CLChile569000
:CMCameroon2379None00
:CNChina8611None00
:COColombia5710000
:CRCosta Rica5068None00
:CUCuba5380119
:CVCape Verde2387None00
:CWCuracao5997-8None00
:CXChristmas Island61900011Delegates to AU
:CYCyprus3578None00
:CZCzech Republic4209None00
:DEGermany4910-12000
:DJDjibouti2538None00
:DKDenmark458None00
:DMDominica110None011NANP, delegates to US
:DODominican Republic110None011NANP, delegates to US
:DZAlgeria2139000
:ECEcuador5939000
:EEEstonia3727-8None00
:EGEgypt2010000
:EHWestern Sahara2129000Delegates to MA
:EREritrea2917000
:ESSpain349None00
:ETEthiopia2519000
:FIFinland3589-10000
:FJFiji6797None00
:FKFalkland Islands5005None00
:FMMicronesia6917None011
:FOFaroe Islands2986None00
:FRFrance339000
:GAGabon2417None00
:GBUnited Kingdom4410000
:GDGrenada110None011NANP, delegates to US
:GEGeorgia9959000
:GFFrench Guiana5949000
:GGGuernsey4410000Delegates to GB
:GHGhana2339000
:GIGibraltar3508None00
:GLGreenland2996None00
:GMGambia2207None00
:GNGuinea2249None00
:GPGuadeloupe5909000
:GQEquatorial Guinea2409None00
:GRGreece3010None00
:GSSouth Georgia5005None00Delegates to FK
:GTGuatemala5028None00
:GUGuam110None011NANP, delegates to US
:GWGuinea-Bissau2457None00
:GYGuyana5927None001
:HKHong Kong8528None001
:HMHeard and McDonald Islands61900011Delegates to AU
:HNHonduras5048None00
:HRCroatia3859000
:HTHaiti5098None00
:HUHungary3690600
:IDIndonesia6210-120001
:IEIreland3539000
:ILIsrael9729000
:IMIsle of Man4410000Delegates to GB
:INIndia9110000
:IOBritish Indian Ocean Territory2467None00
:IQIraq96410000
:IRIran9810000
:ISIceland3547None00
:ITItaly399-10None00Leading 0 retained for landlines
:JEJersey4410000Delegates to GB
:JMJamaica110None011NANP, delegates to US
:JOJordan9629000
:JPJapan81100010
:KEKenya25490000
:KGKyrgyzstan9969000
:KHCambodia8558-90001
:KIKiribati6865None00
:KMComoros2697None00
:KNSaint Kitts and Nevis110None011NANP, delegates to US
:KPNorth Korea85010000
:KRSouth Korea829-100001
:KWKuwait9658None00
:KYCayman Islands110None011NANP, delegates to US
:KZKazakhstan7108810
:LALaos85610000
:LBLebanon9618000
:LCSaint Lucia110None011NANP, delegates to US
:LILiechtenstein4237None00
:LKSri Lanka949000
:LRLiberia2317-9None00
:LSLesotho2668None00
:LTLithuania3708800
:LULuxembourg3529None00
:LVLatvia3718None00
:LYLibya2189000
:MAMorocco2129000
:MCMonaco3778-9None00
:MDMoldova3738000
:MEMontenegro3828000
:MFSaint Martin5909000
:MGMadagascar2619000
:MHMarshall Islands6927None011
:MKNorth Macedonia3898000
:MLMali2238None00
:MMMyanmar958-10000
:MNMongolia9768None001
:MOMacau8538None00
:MPNorthern Mariana Islands110None011NANP, delegates to US
:MQMartinique5969000
:MRMauritania2228None00
:MSMontserrat110None011NANP, delegates to US
:MTMalta3568None00
:MUMauritius2308None00
:MVMaldives9607None00
:MWMalawi2659000
:MXMexico5210None00
:MYMalaysia609-10000
:MZMozambique2589None00
:NANamibia2649000
:NCNew Caledonia6876None00
:NENiger2278None00
:NFNorfolk Island6725-6None00
:NGNigeria234100009
:NINicaragua5058None00
:NLNetherlands319000
:NONorway478None00
:NPNepal97710000
:NRNauru6747None00
:NUNiue6834None00
:NZNew Zealand648-9000
:OMOman9688None00
:PAPanama5078None00
:PEPeru519000
:PFFrench Polynesia6898None00
:PGPapua New Guinea6758None05
:PHPhilippines6310000
:PKPakistan9210000
:PLPoland489None00
:PMSaint Pierre and Miquelon5086None00
:PNPitcairn Islands648-9000Delegates to NZ
:PRPuerto Rico110None011NANP, delegates to US
:PSPalestine9709000
:PTPortugal3519None00
:PWPalau6807None011
:PYParaguay5959000
:QAQatar9748None00
:REReunion2629000
:RORomania409000
:RSSerbia3819000
:RURussia7108810
:RWRwanda2509000
:SASaudi Arabia9669000
:SBSolomon Islands6775-7None00
:SCSeychelles2487None00
:SDSudan2499000
:SESweden469000
:SGSingapore658None001
:SHSaint Helena2904-5None00
:SISlovenia3868000
:SJSvalbard478None00Delegates to NO
:SKSlovakia4219000
:SLSierra Leone2328000
:SMSan Marino37810None00
:SNSenegal2219None00
:SOSomalia2528None00
:SRSuriname5977None00
:SSSouth Sudan2119000
:STSao Tome and Principe2397None00
:SVEl Salvador5038None00
:SXSint Maarten17217None00
:SYSyria9639000
:SZEswatini2688None00
:TCTurks and Caicos110None011NANP, delegates to US
:TDChad2358None00
:TGTogo2288None00
:THThailand6690001
:TJTajikistan9929None810
:TKTokelau6904None00
:TLTimor-Leste6707-8None00
:TMTurkmenistan99388810
:TNTunisia2168None00
:TOTonga6765-7None00
:TRTurkey9010000
:TTTrinidad and Tobago110None011NANP, delegates to US
:TVTuvalu6885None00
:TWTaiwan88690002
:TZTanzania2559000
:UAUkraine3809000
:UGUganda2569000
:USUnited States110None011NANP base rules
:UYUruguay5988000
:UZUzbekistan9989None810
:VAVatican City399-10None00Delegates to IT
:VCSaint Vincent and the Grenadines110None011NANP, delegates to US
:VEVenezuela5810000
:VGBritish Virgin Islands110None011NANP, delegates to US
:VIUS Virgin Islands110None011NANP, delegates to US
:VNVietnam849-10000
:VUVanuatu6785-7None00
:WFWallis and Futuna6816None00
:WSSamoa6855-7None0
:XKKosovo3838000
:YEYemen9679000
:YTMayotte2629000Delegates to RE
:ZASouth Africa279000
:ZMZambia2609000
:ZWZimbabwe2639000

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โ€‹

VariableValueDescription
destination_numberE.164 formatNormalized destination number
tas_destination_numberE.164 formatSame as destination_number (both set for compatibility)
effective_caller_id_numberE.164 formatNormalized 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