How to Configure Teams Phone Number Translation Rules in PowerShell Using CsTeamsTranslationRule

In enterprise telecommunications migrations from legacy PBX infrastructure to Microsoft Teams Phone, users are accustomed to legacy dialing habits. Employees frequently dial short internal extensions (such as 4-digit or 5-digit extensions like 4100), dial local 7-digit numbers without regional area codes, or dial outbound trunk prefixes (such as dialing 9 or 0 before an external number). However, standard Session Initiation Protocol (SIP) gateways, cloud PSTN providers, and Microsoft Teams Phone require normalized global E.164 phone numbers (e.g. +14155550100) to route calls accurately.

To bridge the gap between human dialing habits and strict E.164 routing requirements, Microsoft Teams provides Number Translation Rules, configured via the CsTeamsTranslationRule cmdlet family in PowerShell. Number translation rules utilize regular expression (regex) pattern matching and substitution syntax to dynamically transform dialed numbers before they are evaluated by Teams dial plans, voice routing policies, and Session Border Controllers (SBCs). This guide explains how Teams translation rules operate, how regex transformation patterns function, and how to create, test, and assign translation rules using PowerShell.

Architecture of Teams Phone Number Translation Rules

Number translation occurs during the early call-setup phase within the Microsoft Teams cloud PBX processing pipeline:

• Pattern Matching: A translation rule defines a regular expression pattern (-Pattern) that evaluates the raw string dialed by the user on their Teams desktop client, mobile app, or physical SIP desk phone.
• Translation Substitution: When the dialed string matches the pattern, the rule executes an expansion or transformation string (-Translation) using standard regex back-references (e.g. $1, $2) to convert the number into an international E.164 formatted string.
• Direct Routing and SBC Integration: In Direct Routing and Operator Connect deployments, translation rules can also be applied to inbound calls arriving from Session Border Controllers (SBCs) to convert incoming carrier numbers into domestic formats or strip carrier routing prefixes before presenting the call to Teams users.
• Dial Plan Association: Once defined via New-CsTeamsTranslationRule, translation rules are linked to tenant dial plans (CsTeamsDialPlan) or voice normalization policies.

Configuring translation rules centrally via PowerShell guarantees seamless dialing across disparate branch offices, eliminating user confusion and failed call connection errors.

Prerequisites and PowerShell Module Connection

Managing Teams translation rules requires version 4.9.0 or later of the Microsoft Teams PowerShell module and an account assigned the Teams Administrator or Global Administrator role in Microsoft Entra ID.

Open an elevated PowerShell prompt and check your module version:

Get-Module -ListAvailable -Name MicrosoftTeams

If needed, install or update the module from the PowerShell Gallery:

Install-Module -Name MicrosoftTeams -Force -AllowClobber -Scope CurrentUser

Connect to your Microsoft Teams tenant:

Connect-MicrosoftTeams

Verify your active administrative connection:

Get-CsTenant | Select-Object DisplayName, TenantId

Inspecting Existing Translation Rules

To inspect all currently registered number translation rules across your Microsoft Teams tenant, execute Get-CsTeamsTranslationRule:

Get-CsTeamsTranslationRule

PowerShell outputs configured translation rules:

Identity    : FourDigitExtension-US
Pattern     : ^(\d{4})$
Translation : +1415555$1
Description : Translates 4-digit internal extensions to San Francisco E.164 DIDs

Identity    : OutsideLinePrefix-9
Pattern     : ^9(\d{10})$
Translation : +1$1
Description : Strips legacy '9' outside-line access prefix and normalizes to US E.164

To view specific details of an individual rule, pass the -Identity parameter:

Get-CsTeamsTranslationRule -Identity "FourDigitExtension-US" | Format-List

Creating Number Translation Rules for Common Dialing Scenarios

The New-CsTeamsTranslationRule cmdlet uses regular expressions to handle diverse enterprise telecommunications workflows.

Scenario 1: Converting 4-Digit Extensions to Full E.164 Numbers

In this common scenario, employees dial 4-digit internal extensions (e.g. dialing 4100). The rule must convert the string into the full E.164 Direct Inward Dial (DID) format (+14155554100):

New-CsTeamsTranslationRule `
    -Identity "Extension-4Digit-US" `
    -Description "Normalizes 4-digit extensions to US DID numbers" `
    -Pattern '^(\d{4})$' `
    -Translation '+1415555$1'

Scenario 2: Stripping Outside-Line Access Prefixes (Dialing ‘9’)

Users transitioning from legacy PBX systems often instinctively dial 9 before external phone numbers. To strip the leading 9 and normalize a 10-digit domestic US number to E.164:

New-CsTeamsTranslationRule `
    -Identity "Strip-9-Prefix" `
    -Description "Strips leading 9 from 10-digit domestic calls" `
    -Pattern '^9(\d{10})$' `
    -Translation '+1$1'

Scenario 3: Normalizing Local 7-Digit Dialing to Regional Area Codes

To allow users in a local London office to dial domestic 8-digit numbers without typing the national area code (020):

New-CsTeamsTranslationRule `
    -Identity "London-Local-8Digit" `
    -Description "Normalizes 8-digit local London calls to UK E.164 format" `
    -Pattern '^(\d{8})$' `
    -Translation '+4420$1'

Testing Translation Rules in PowerShell

Before deploying a translation rule to production user dial plans, verify that your regular expression pattern accurately parses target strings and produces the expected E.164 output using Test-CsTeamsTranslationRule:

# Test 4-digit extension translation
Test-CsTeamsTranslationRule -Identity "Extension-4Digit-US" -PhoneNumber "4150"

# Test prefix stripping translation
Test-CsTeamsTranslationRule -Identity "Strip-9-Prefix" -PhoneNumber "92125550199"

PowerShell outputs the transformed result:

TransformedNumber : +14155554150
TransformedNumber : +12125550199

If the input number does not match the rule’s regular expression pattern, Test-CsTeamsTranslationRule returns empty or outputs the untransformed string, confirming that non-matching numbers pass through unaltered.

Modifying and Removing Translation Rules

To update an existing rule’s translation pattern or description, use Set-CsTeamsTranslationRule:

Set-CsTeamsTranslationRule `
    -Identity "Extension-4Digit-US" `
    -Translation '+1415556$1'

To permanently delete an obsolete translation rule:

Remove-CsTeamsTranslationRule -Identity "Strip-9-Prefix"

Deploying accurate translation rules ensures that all dialed telephone numbers normalize into standard E.164 formats, streamlining routing across Direct Routing session border controllers, Operator Connect carriers, and Microsoft Teams Calling Plans.