Voice translation rules have tripped up many an engineer, especially when troubleshooting an existing router that you may not have installed. In those situations, it can be easy to misunderstand the subtleties of voice translation rules when quickly reviewing a production configuration.
So, by popular demand, this post will serve as a collection of many examples showing various methods of using voice translation rules. Check back periodically, as the number of examples on this page will grow quickly over time. As always, I'd love to have comments and suggestions for scenarios that should be included and explained.
In case you need to review the syntax of a voice translation rule, please review this earlier post that goes over syntax, including wildcards, number slicing and valid characters (and their meanings).
Applying Voice Translation-Rules
In order to apply a voice translation-rule, you must apply it to a voice translation-profile. Voice translation-profiles can then be applied in a number of ways to dial-peers and voice ports.
See a quick example below, or this very comprehensive document for much greater detail.
voice translation-rule 1
rule 1 /212/ /9/
voice translation-profile myprofile
translate calling 1
dial-peer voice 10 pots
translation-profile outgoing myprofile
Basic Match and Replace
example 1.1
In this example, only the first occurrence of the match-pattern will be changed to the replace-pattern.
voice translation-rule number
rule precedence /match-pattern/ /replace-pattern/
voice translation-rule 1
rule 1 /123/ /890/
rule 1 /123/ /890/
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
Matched with rule 1
Original number: 1234 Translated number: 8904
router#test voice translation-rule 1 1123
Matched with rule 1
Original number: 1123 Translated number: 1890
router#test voice translation-rule 1 1123123
Matched with rule 1
Original number: 1123123 Translated number: 1890123
example 1.2
In this example, the match-pattern will be changed to the replace-pattern only when it occurs at the beginning of a number. This is indicated by the leading "^" in the match-pattern.
voice translation-rule 1
rule 1 /^123/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
Matched with rule 1
Original number: 1234 Translated number: 8904
router#test voice translation-rule 1 1234123
Matched with rule 1
Original number: 1234123 Translated number: 8904123
router#test voice translation-rule 1 1123
No match. "123" does not occur at beginning.
rule 1 /^123/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
Matched with rule 1
Original number: 1234 Translated number: 8904
router#test voice translation-rule 1 1234123
Matched with rule 1
Original number: 1234123 Translated number: 8904123
router#test voice translation-rule 1 1123
No match. "123" does not occur at beginning.
example 1.3
In this example, the match-pattern will be changed to the replace-pattern only when it occurs at the end of a number. This is indicated by the trailing "$" in the match-pattern.
voice translation-rule 1
rule 1 /123$/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
No match. "123" does not occur at the end of the number.
router#test voice translation-rule 1 1234123
Matched with rule 1
Original number: 1234123 Translated number: 1234890
router#test voice translation-rule 1 1123
Matched with rule 1
Original number: 1123 Translated number: 1890
rule 1 /123$/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
No match. "123" does not occur at the end of the number.
router#test voice translation-rule 1 1234123
Matched with rule 1
Original number: 1234123 Translated number: 1234890
router#test voice translation-rule 1 1123
Matched with rule 1
Original number: 1123 Translated number: 1890
example 1.4
In this example, the match-pattern will be changed to the replace-pattern only when it matches exactly. This is indicated by using both the leading "^" and the trailing "$" in the match-pattern which has the combined effect of saying "match the pattern that both begins AND ends within the number".
voice translation-rule 1
rule 1 /^123$/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
rule 1 /^123$/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
No match. "123" does not occur at the end of the number.
router#test voice translation-rule 1 1123
No match. "123" does not occur at the beginning.
No match. "123" does not occur at the end of the number.
router#test voice translation-rule 1 1123
No match. "123" does not occur at the beginning.
Using Wildcards
example 2.1
Replace any number that is five digits in length that begins with "88" with the number "9999000".
voice translation-rule 1
rule 1 /^88.../ /9999000/
router#test voice translation-rule 1 88222
Matched with rule 1
Original number: 88222 Translated number: 9999000
router#test voice translation-rule 1 89123
No Match. The number does not begin with 88.
No Match. The number does not begin with 88.
router#test voice translation-rule 1 881234
No Match. The number contains too many digits.
router#test voice translation-rule 1 8812
No Match. The number contains too few digits.
example 2.2
Replace any numbers with "9995000". ".*" is a wildcard that includes all numbers, including null.
voice translation-rule 2
rule 1 /.*/ /9995000/
router#test voice translation-rule 2 123
Matched with rule 1
Original number: 123 Translated number: 9995000
router#test voice translation-rule 2 86573
Matched with rule 1
Original number: 86573 Translated number: 9995000
router#test voice translation-rule 2 ""
Matched with rule 1
Original number: <NULL> Translated number: 9995000
example 2.3
This example replaces all numbers, except null, with "9995000". ".+" includes all numbers, except null.
voice translation-rule 1
rule 1 /.+/ /9995000/
router#test voice translation-rule 1 89555
Matched with rule 1
Original number: 89555 Translated number: 9995000
router#test voice translation-rule 1 212
Matched with rule 1
Original number: 212 Translated number: 9995000
router#test voice translation-rule 1 ""
No match. <NULL> is not included in match pattern.
example 2.4
This example replaces any number that starts with a combination of eights with "999" instead of the eight(s).
voice translation-rule 5
rule 1 /^8+/ /999/
router#test voice translation-rule 5 85551212
Matched with rule 1
Original number: 85551212 Translated number: 9995551212
router#test voice translation-rule 5 885551212
Matched with rule 1
Original number: 885551212 Translated number: 9995551212
router#test voice translation-rule 5 8885551212
Matched with rule 1
Original number: 888123456 Translated number: 9995551212
router#test voice translation-rule 5 5551212
No match. Number does not begin with eight.
example 2.5
Translate any number to null, including null. The wildcard combination "^.*" matches all numbers, including null. If you had wanted to match only null, you could have used "^$".
voice translation-rule 1
rule 1 /^.*/ / /
router#test voice translation-rule 1 2001
Matched with rule 1
Original number: 2001 Translated number: <NULL>
router#test voice translation-rule 1 5551212
Matched with rule 1
Original number: 5551212 Translated number: <NULL>
router#test voice translation-rule 1 5551212
Matched with rule 1
Original number: <NULL> Translated number: <NULL>
Number Slicing (and Dicing)
Voice translation rules have the ability to slice the number into smaller parts, manipulate each part individually and then put the number back together again. This technique is called "number slicing". It can appear very complicated and gives many engineers difficulty at first, but with some practice you will soon master the technique.
example 3.1
This example is meant to provide some explanation of a typical voice translation rule using number slicing at a higher level. Consider the following rule:
/ (x\) y\ (z\) / / a \1 \2 /
- Split the matched number into three sets of x, y, and z.
- The backward slash (\) indicates the where to slice up the number.
- The brackets () indicate which sets you want to reuse in the replacement pattern.
- The a represents additional digits to insert into the replacement number.
Set 1 inherits the value of x.
Set 2 inherits the value of z.
Expression y is not reused.
The replacement number is a concatenated number: axz
example 3.2
In this example, the number of 55866 will be replaced with 85566 using number slicing. While this could be accomplished using a simpler rule, it serves our purposes here to demonstrate number slicing. Note that "^" and "$" are used to designate that the match pattern must exist at both the beginning and end of a number (essentially an explicit match).
voice translation-rule 1
rule 1 /^\(55\)8\(66\)$/ /8\1\2/
Set 1: 55
Set 2: 66
Ignore: 8
router#test voice translation-rule 1 55866
Matched with rule 1
Original number: 55866 Translated number: 85566
router#test voice translation-rule 1 12345
No match. The match pattern is not satisfied.
router#test voice translation-rule 1 55867
No match. The match pattern is not satisfied.
router#test voice translation-rule 1 55466
No match. The match pattern is not satisfied.
Manipulating Number Type and Plan
When interfacing with different telcos around the world, you will find that all are not created equally. Some will require that calls be send with a specific numbering plan for the type of call to be handled correctly. Using voice translation rules, the plan or type can be manipulated as required or the call can be blocked.
example 4.1
If a number starts with "4" and the type is "national", the rule adds "99" as a prefix. If the type is "international", the rule adds "999" as the prefix. This simulates the scenario in which the telco requires an access code when placing an national or international call.
voice translation-rule 1
rule 1 /^4/ /994/ type national national
rule 2 /^4/ /9994/ type international international
router#test voice translation-rule 1 442195555 type national
Matched with rule 1
Original number: 442195555 Translated number: 99442195555
Original number type: national Translated number type: national
Original number plan: none Translated number plan: none
router#test voice translation-rule 1 442195555 type international
Matched with rule 2
Original number: 442195555 Translated number: 999442195555
Original number type: international Translated number type: international
Original number plan: none Translated number plan: none
router#test voice translation-rule 1 842195555 type international
No Match. Does not begin with "4".
example 4.2
This rule simply matches any four-digit number that starts with "8" and adds the number "04421955" as a prefix while stripping the "8", and sets the plan to "isdn" and the type to "national".
voice translation-rule 1
rule 1 /^8\(...$\)/ /04421955\1/ type unknown national plan unknown isdn
router#test voice translation-rule 1 8150 type unknown plan unknown
Matched with rule 1
Original number: 8150 Translated number: 04421955150
Original number type: unknown Translated number type: national
Original number plan: unknown Translated number plan: isdn
router#test voice translation-rule 1 6150 type unknown plan unknown
No Match. Does not begin with 8.
router#test voice translation-rule 1 81501 type unknown plan unknown
No Match. Does not contain the correct number of digits (4).
Blocking Calls
Rejecting or blocking calls can easily be done with voice translation-rules. Add the reject keyword to the syntax as shown in these examples. The call must match the match-prefix in order to be dropped.
example 5.1
Rejects all calls starting with "900".
rule 1 reject /^900/
router#test voice translation-rule 10 8005551212
No Match. Does not begin with 900.
router#test voice translation-rule 10 9005551212
Call blocked by rule 1
Special Cases
This section contains examples that show strategies to accomplish very common digit manipulation requirements.
example 6.1
This is a very useful translation rule that will strip off all but the last 4 digits. Note that digits that will be retained must be enclosed in () within the match pattern.
rule 1 /^.*\(....\)/ /\1/
router#test voice translation-rule 1 5551212
Matched with rule 1
Original number: 5551212 Translated number: 1212
router#test voice translation-rule 1 2125551212
Matched with rule 1
Original number: 2125551212 Translated number: 1212
Suggestions Welcome
If you have a suggestion or example that should be included - please let me know! I'll give you credit and link back to your blog, website or twitter - your choice!
More Information
Voice Translations in Cisco IOS Gateways This is an 18-page PDF that goes into great detail about many types of translation rules, and how to apply them in different situations. Highly recommended!