Microsoft Dynamics 365 Blog

This customization is designed to call the ‘Microsoft® Translator’ service from within CRM. This example uses a custom button, included in an entity form, to call the service and translate text (which has been selected by the user) into another language.

This document describes the steps required to include the custom button on a form, how to call the service and how to set the language of both the source and target text.

NOTE: This customization is designed for use with Internet Explorer (IE) 7 or higher.

Adding the “Translate” button to a form

– Navigate to “Settings\Customizations\Export Customization”

– Select “ISVconfig” and click on “Export Selected Customizations”

– Save the “” file to a convenient location and expand it so that you can edit the customizations.xml file.

– Add these lines to the toolbar section for your chosen entity:

<Button Icon="/_imgs/ico_18_debug.gif" JavaScript="crmTranslator.TranslateText()">
<Title LCID="1033" Text="ToolBar Translate" />
<ToolTip LCID="1033" Text="Translate selected text" />

– Now, click on “Import customizations” and upload the customizations.xml file

– Publish your customizations

– Navigate to “Settings\Administration\System Settings” and in the “Customizations” tab ensure that the client you intend to view this customization with is selected.

You should now be able to see the button on your chosen form.


Changing the Title and Tooltip text of the button

To change (edit) the text that appears in the button, or the tooltip, simply change the highlighted portions as indicated below:

<Button Icon="/_imgs/ico_18_debug.gif" JavaScript="Tx_Selected();">
<Title LCID="1033" Text="ToolBar Translate" />
<ToolTip LCID="1033" Text="Translate selected text" />

You will again need to ‘import’ and ‘publish’ the customization before you will see your changes.

If localizing the Title and Tooltip, you should also change the LCID reference when editing the text. The example here shows a change to the French LCID:

<Button Icon="/_imgs/ico_18_debug.gif" JavaScript="Tx_Selected();">
<Title LCID="1036" Text="Traduire" />
<ToolTip LCID="1036" Text="Traduire du texte sélectionné" />

In a multi-lingual deployment of CRM (where additional language packs are installed) you may want the button text and tool tip to change based on a user’s language settings. In this case you will need to add a new Locale ID (LCID) line for each language you’d like to included, both in the Title and Tooltip section. In the below example, both English and French are included:

<Button Icon="/_imgs/ico_18_debug.gif" JavaScript="Tx_Selected();">
<Title LCID="1033" Text="ToolBar Translate" />
<Title LCID="1036" Text="Traduire" />
<ToolTip LCID="1033" Text="Translate selected text" />
<ToolTip LCID="1036" Text="Traduire du texte sélectionné" />

For a full list of Locale ID codes (LCID Dec) assigned by Microsoft, please see the reference on the Microsoft Developer Network.

Adding the “Powered by” gif to the translation window

To add the “poweredby.gif” image to the translation window, you should create a folder for your customization in the “CRMWeb\ISV folder on your server, for example “CRMWeb\ISV\CRMTranslator”. “Copy the gif file (poweredby.gif) included in the download into to this folder.


Add the code to the form’s OnLoad() function

You have specified the script action "crmTranslateSample.TranslateText()", so you now need to define this. You need to firstly define the function in the forms “OnLoad()” event. Then create the namespace “crmTranslateSample” and attach the function. This is done to safeguard against upgrades and QFE’s potentially introducing CRM functions with the same name which we could then break with our duplicate function name – for more info and another example see this blog post:

NOTE: You will need you own Developer AppId to supply in the call to “Translate” (see info here: )

– Navigate to “Settings\Customizations\Customize Entities”

– Click on the entity to whose form you want to add the translator – for example: “account”

– When the web dialog opens, click on “Forms & Views” and double-click on “Form” – the main application form.

– Click on Form properties

– In the “Event list”, select “OnLoad()” and click “Edit”

– Add the code in the attached CrmTranslatorCode.txt to this event editor, this consists of

  1. Tx_Selected() – the function which does the work
  2. Definition of the crmTranslator object to use as a namespace, and couple of lines to:
    • Attach the Tx_Selected() function to this namespace (as crmTranslator.TranslateText)
    • Attach the namespace to the window so that it is available when the button calls it.
// Tx_Selected, function where the work is done
Tx_Selected = function() 
   // Provide your own Application ID.
    var appId = "YOUR APP ID";
      var paramString = "";
      paramString += "appId=";
      paramString += appId;
      paramString += "&from=en&to=es";

   // Get the text to be translated.
   var selectionObject = document.selection;
   if (selectionObject.type == 'Text') 
          var selectedText = selectionObject.createRange();
         var xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");'POST', paramString, false);
         var ret =   xmlhttp.send(selectedText .text);
         var msg = '<table border="1"><tr><td   WIDTH=450>';
         msg += xmlhttp.responseText;
         msg += '</td></tr></table>';
      catch (e)
          var msg = "<p>There was a problem with the Search</p>";
          if (e.number == -2146828218)
               msg += "<p>Your Internet Explorer security settings ";
               msg += "for this zone do not allow ";
               msg += "access to data sources across domains. </p>";
               msg += "<p>You must set your Internet Explorer ";
               msg += "security settings to allow access ";
               msg += "to data sources across domains. ";
               msg += "For more information see ";
               msg += "<a href='";
               msg += "ie6/using/howto/security/setup.mspx#EQCAC' ";
               msg += "Target='_blank' >Setting Up Security Zones";
               msg += "</a>.</p>";

      txWindow ="", "mywindow","status = 0, scrollbars = 1, height = 200, width = 500,  resizable = 0");

      txWindow.document.write('<img src="/ISV/CRMTranslator/poweredby.gif" alt="" />');

       //write the text to the window in a table
    } //end of the 'if' block

//Create an arbitrary object to serve as a namespace
var crmTranslator= new Object();

//Attach the function to the crmTranslator
crmTranslator.TranslateText = Tx_Selected;

//Attach the crmTranslatorto the window so it is globally available
window.crmTranslator = crmTranslator;

– Ensure that the Event is enabled checkbox is checked and click “Ok”

– Click “Ok” on the “Form Properties” dialog also

– Save and Close your form

– You will, again, need to ‘publish’ this customization before it is usable.

The CRM SDK is available here

You should find the crmsdk4.chm file which comes with a useful reference guide especially the sections like “Customization Best Practices”, “Accessing Web Services in Jscript” and “ISV.Config XML Reference”

For another code example and more information on the consumption of external web services from within a CRM form, see this blog post

Setting the source and target languages

In the example given, the “from” parameter is set for English source text to be translated into Spanish:

var xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");'POST', '', false);

To change the source/target languages you need to edit the form Onload () function to reflect the desired languages – for example, “from=de&to=fr” for German source text to be translated to French.

It is important that you use languages which are;

a) supported by the service, and

b) you must use the recognized ISO 639-1 language code:


Using the “Translate” button

The example given here is in the Accounts form, but the process is the same for any entity.

– Navigate to “Workplace\Accounts” (or the entity you have included the function in)

– Open any record

– Select the text in any free text field or edit box, on any tab (in the example we’ve highlighted the “Description” text on the “Details” tab


– Click on the translation button in the toolbar.


– Microsoft Translator is invoked and the returned translation is displayed in a pop-up as follows (i.e.; the selected text is translated to Spanish)


Any and all use of the Microsoft Translator service must be in full compliance with the Live Services ‘Terms of Service’ ( and specifically the Microsoft Service Agreement here-

For more information on the use of the MS translator see:


Dermot Boyle

We're always looking for feedback and would like to hear from you. Please head to the Dynamics 365 Community to start a discussion, ask questions, and tell us what you think!