7.2 Voice Translation Rules and Translation Profiles
Key Takeaways
Voice translation rules use regular expressions to match and replace calling, called, and redirecting numbers, replacing legacy num-exp and dial-peer digit manipulation.
Translation rule syntax
rule <id> /<match>/ /<replace>/ [type <match-type> <replace-type>] [plan <match-plan> <replace-plan>]allows simultaneous digit and ISDN Type of Number (TON) / Numbering Plan Identification (NPI) manipulation.Regular expression capture groups enclosed in parentheses ( ) store matching sub-strings that are recalled in replacement patterns using back-references (\1, \2 through \9).
Voice translation profiles bind translation rules to functional call roles: translate calling, translate called, translate redirect-called, and translate redirect-target.
Applying a translation profile with translation-profile incoming normalizes digits before dial peer matching and call routing, whereas translation-profile outgoing formats digits immediately before transmission across the egress trunk.
7.2 Voice Translation Rules and Translation Profiles
Digit manipulation is a cornerstone of enterprise collaboration engineering. In modern enterprise dial plans, internal endpoints typically register with 4-digit, 5-digit, or 10-digit extensions, whereas public telecom carriers demand fully qualified E.164 international numbering (+14155551212) or local 7-digit strings. Cisco IOS XE Voice Translation Rules and Voice Translation Profiles provide a flexible, high-performance regular expression engine that manipulates calling party numbers (ANI), called party numbers (DNIS), and redirecting numbers before routing or transmitting calls.
1. Voice Translation Rule Architecture & Syntax
Voice translation rules replace older legacy methods (such as num-exp, prefix, and forward-digits). Translation rules are defined globally under voice translation-rule <tag> and contain individual, sequential rule statements:
voice translation-rule <rule-tag>
rule <rule-number> /<match-pattern>/ /<replace-pattern>/ [type <match-type> <replace-type>] [plan <match-plan> <replace-plan>]
Parameter Breakdown
<rule-tag>: Unique numerical identifier (e.g.,10) designating the translation rule group.rule <rule-number>: Sequence number (1 through 100) determining the evaluation order within the group. The gateway evaluates rules in ascending numerical order; the first rule that matches the input string executes, and all subsequent rules in that group are skipped./<match-pattern>/: Delimited regular expression defining the digit sequence and structure to match./<replace-pattern>/: Delimited string defining the substituted digit string, incorporating literal digits, prefixes, or back-referenced capture groups.[type ...]: Optional modifier matching and converting the ISDN Type of Number (TON).[plan ...]: Optional modifier matching and converting the ISDN Numbering Plan Identification (NPI).
+-----------------------------------------------------------------------------------------+
| TRANSLATION RULE REGEX ENGINE MECHANICS |
| |
| Input String: "4155551234" |
| |
| Rule: rule 1 /^\(415\)\(555....\)$/ /+1\1\2/ |
| |
| Pattern Component Function |
| ----------------- -------------------------------------------------- |
| ^ Anchor to start of string |
| \(415\) Capture Group 1 -> Captures "415" |
| \(555....\) Capture Group 2 -> Captures "5551234" |
| $ Anchor to end of string |
| /+1\1\2/ Replacement: Prepend "+1", append Group 1, append Group 2 |
| |
| Output String: "+14155551234" |
+-----------------------------------------------------------------------------------------+
2. Regular Expression Wildcards, Capture Groups & Back-References
The IOS XE translation engine uses specialized regular expression symbols tailored for telephony digit strings:
| Regex Symbol | Technical Definition | Example Match | Resulting Match Behavior |
|---|---|---|---|
^ | Start-of-string anchor | ^415 | Matches only if the digit string begins with 415. |
$ | End-of-string anchor | 1212$ | Matches only if the digit string ends with 1212. |
. | Single digit wildcard | ^2...$ | Matches any 4-digit number starting with 2 (e.g., 2001, 2999). |
[ ] | Character class / range | ^[2-9] | Matches any single digit between 2 and 9 in the first position. |
.* | Any digits, zero or more of them | ^911.* | Matches strings starting with 911 regardless of trailing digits. |
\( \) | Capture group delimiter | ^\(2...\)$ | Captures the matched 4-digit string into a numbered memory buffer. |
\1 - \9 | Back-reference index | +1415555\1 | Recalls the exact digits stored in capture group 1 through 9. |
Capture Groups and Back-References in Practice
Capture groups allow an engineer to parse variable digit strings and reassemble them dynamically:
- Up to nine capture groups (
\1through\9) can be created per rule. - In Cisco IOS XE CLI, literal parentheses must be escaped with a backslash:
\(and\). - Example: Converting 10-digit North American numbers to +E.164:
Input:voice translation-rule 1 rule 1 /^\([2-9]..[2-9]......\)$/ /+1\1/4155551234-> Group 1 captures4155551234-> Output:+14155551234.
3. ISDN Number Types (TON) and Numbering Plans (NPI)
When interfacing with telecom service providers over ISDN PRI or carrier SIP trunks, transmitting correct Type of Number (TON) and Numbering Plan Identification (NPI) metadata is mandatory for emergency routing (E911), caller identification display, and toll billing.
Supported Number Types (type keyword)
subscriber: Local directory numbers (e.g., 7-digit local PSTN numbers).national: Long-distance numbers within the country code (e.g., 10-digit North American numbers with area code).international: International numbers including country code (e.g., E.164 format without leading access codes).unknown: Default unclassified number type (used when the network cannot determine classification).abbreviated: Short dialing codes (e.g., internal tie-lines or 3-digit service numbers).
Supported Numbering Plans (plan keyword)
isdn: The ISDN/telephony numbering plan (ITU-T E.164), the usual choice for PSTN numbers.data,telex,national: Other plan identifiers, rarely used in modern voice networks.private: Enterprise private numbering plan (e.g., internal corporate site codes).unknown: Unspecified numbering plan.
voice translation-rule 50
rule 1 /^\([2-9]......\)$/ /\1/ type unknown subscriber plan unknown isdn
rule 2 /^\([2-9]..[2-9]......\)$/ /\1/ type unknown national plan unknown isdn
rule 3 /^011\(.*\)$/ /\1/ type unknown international plan unknown isdn
4. Testing Translation Rules via the CLI
Cisco IOS XE provides an EXEC mode command to verify translation rules before applying them to production voice traffic:
Router# test voice translation-rule <rule-tag> <input-string> [type <type>] [plan <plan>]
Diagnostic Test Examples
Testing rule 10 from Scenario 1 below, which strips the access code 9 and normalizes to +E.164:
Router# test voice translation-rule 10 914155551234
Matched with rule 1
Original number: 914155551234 Translated number: +14155551234
Original number type: none Translated number type: none
Original number plan: none Translated number plan: none
Router# test voice translation-rule 50 4155551212 type unknown plan unknown
Matched with rule 2
Original number: 4155551212 Translated number: 4155551212
Original number type: unknown Translated number type: national
Original number plan: unknown Translated number plan: isdn
If the input digits do not match any rule in the rule group, the router outputs:
Router# test voice translation-rule 1 1234
Did not match with any of the rules
5. Voice Translation Profiles
A Voice Translation Profile is an administrative container that binds individual translation rules to specific telephony functional roles. While a translation rule simply defines how digits are transformed, a translation profile defines which party's digits (calling, called, or redirecting) are transformed.
voice translation-profile <profile-name>
translate calling <rule-tag>
translate called <rule-tag>
translate redirect-called <rule-tag>
translate redirect-target <rule-tag>
Functional Role Binding
translate calling <rule-tag>: Applies the specified rule group to the Calling Party Number (ANI). Used for outbound caller ID presentation or inbound caller ID normalization.translate called <rule-tag>: Applies the specified rule group to the Called Party Number (DNIS). Used for stripping off-net access digits or expanding extensions.translate redirect-called <rule-tag>: Manipulates the original redirecting number (e.g., the forwarded mailbox extension in SIP Diversion headers or ISDN Redirecting Number IEs).translate redirect-target <rule-tag>: Manipulates the target destination to which a call is being redirected.
6. Inbound vs. Outbound Profile Application
Translation profiles are bound directly to dial peers using either translation-profile incoming <name> or translation-profile outgoing <name>:
[ PSTN Trunk ]
|
v (Ingress Leg)
+-----------------------------------------------------------------------------------+
| 1. INBOUND DIAL PEER: translation-profile incoming <NORMALIZE> |
| - Called Number: 4155552001 -> Converted to internal extension 2001 |
| - Calling Number: 4085559999 -> Normalized to +E.164 +14085559999 |
+-----------------------------------------------------------------------------------+
|
v
[ DIAL PLAN ROUTING ENGINE: Matches Internal Extension 2001 ]
|
v (Egress Leg)
+-----------------------------------------------------------------------------------+
| 2. OUTBOUND DIAL PEER: translation-profile outgoing <CALLER-ID-MASK> |
| - Calling Extension 2001 -> Masked with corporate DID +14155552000 |
| - Called Number 914085551212 -> Strips '9', sends 14085551212 to Telco |
+-----------------------------------------------------------------------------------+
|
v
[ CUCM / Telco Destination ]
Application Scope
translation-profile incoming <name>:- Evaluated immediately upon call arrival on the inbound call leg.
- Digit transformations occur before outbound dial peer matching takes place.
- Crucial for E.164 normalization, stripping carrier prefixes, or converting incoming 10-digit DIDs into 4-digit extensions that match internal CUCM directory numbers.
translation-profile outgoing <name>:- Evaluated on the outbound call leg after dial peer matching has completed.
- Digit transformations occur immediately before the signaling message (SIP INVITE or Q.931 SETUP) is placed on the physical or IP wire.
- Crucial for outbound Caller ID masking, adding PSTN carrier routing codes, or formatting carrier-compliant E.164 dialing.
7. Real-World Configuration Scenarios
Scenario 1: Stripping Access Digit 9 & Prepending Country Code
voice translation-rule 10
rule 1 /^91\([2-9]..[2-9]......\)$/ /+1\1/
rule 2 /^9\([2-9]......\)$/ /+1415\1/
!
voice translation-profile STRIP-9-NORMALIZE
translate called 10
!
dial-peer voice 101 voip
description Outbound SIP Trunk to CUBE / Telco
destination-pattern 9T
translation-profile outgoing STRIP-9-NORMALIZE
session protocol sipv2
session target ipv4:192.168.10.1
Scenario 2: Outbound Caller ID Presentation (Extension to DID Masking)
Transforms internal 4-digit extensions starting with 2 into full company DIDs (+1-415-555-2XXX) while setting the number type to National:
voice translation-rule 20
rule 1 /^\(2...\)$/ /+1415555\1/ type unknown national plan unknown isdn
!
voice translation-profile OUTBOUND-CALLER-ID
translate calling 20
!
dial-peer voice 200 pots
description Egress PRI Trunk to PSTN
destination-pattern 9[2-9]......
translation-profile outgoing OUTBOUND-CALLER-ID
port 0/2/0:23
A voice engineer configures this translation rule on a Cisco IOS XE voice gateway:
voice translation-rule 1
rule 1 /^\([2-9]..\)\([2-9]......\)$/ /+1\1\2/
If the input digit string is 4155551234, what is the resulting translated output?
4155551234
+1415
+14155551234
14155551234
Where must a voice translation profile be applied if an engineer needs to normalize incoming called numbers (DNIS) before the voice gateway evaluates its outbound dial peers for call routing?
Globally under the voice service voip sip configuration mode.
On the outbound dial peer using the translation-profile outgoing command.
Directly on the physical serial voice-port interface using translate-called.
On the inbound dial peer using the translation-profile incoming command.
An engineer executes the command 'test voice translation-rule 5 2001' on a voice gateway. The CLI outputs 'Did not match with any of the rules'. What does this output indicate?
The gateway's voice-card DSP resources are exhausted or administratively shut down.
The translation profile has not been assigned to an active dial peer.
None of the regular expression match patterns defined in translation-rule 5 matched the input string 2001.
The test command requires the translation profile name instead of the rule number, so the syntax was rejected.
Sections you finish are checked off in the contents.