Voice Translation Rules : Examples

Updated:  4/14/2011

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/  

    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 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.

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

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

    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.

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.

    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!