Quickstart: Build, deploy, and use a custom model for translation

This article provides step-by-step instructions to build a translation system with Custom Translator.


  1. To use the Custom Translator Portal, you will need a Microsoft account or Azure AD account (organization account hosted on Azure) to sign in.

  2. A subscription to the Translator Text API via the Azure portal. You will need the Translator Text API subscription key to associate with your workspace in Custom Translator. See how to sign up for the Translator Text API.

  3. When you have both of the above, sign in to the Custom Translator portal to create workspaces, projects, upload files and create/deploy models.


Custom Translator does not support creating workspace for Translator Text API resource that was created inside Enabled VNET.

Create a workspace

If you are first time user, you will be asked to agree to the Terms of Service, to create a workspace and to associate your workspace with Microsoft Translator Text API subscription.

Create workspace Create workspace image 1 Create workspace image 2 Create workspace image 3 Create workspace image 4 Create workspace image 5 Create workspace image 6

On subsequent visits to the Custom Translator portal, navigate to the Settings page where you can manage your workspace, create more workspaces, associate your Microsoft Translator Text API subscription key with your workspaces, add co-owners, and change a subscription key.

Create a project

On the Custom Translator portal landing page, click New Project. On the dialog you can enter your desired project name, language pair, and category, as well as other relevant fields. Then, save your project. For more details, visit Create Project.

Create project

Upload documents

Next, upload training, tuning and testing document sets. You can upload both parallel and combo documents. You can also upload dictionary.

You can upload documents from either the documents tab or from a specific project's page.

Upload documents

When uploading documents, choose the document type (training, tuning, or testing), and the language pair. When uploading parallel documents, you'll need to additionally specify a document name. For more details, visit Upload document.

Create a model

When all your required documents are uploaded the next step is to build your model.

Select the project you've created. You'll see all the documents you've uploaded that share a language pair with this project. Select the documents that you want included in your model. You can select training, tuning, and testing data or select just training data and let Custom Translator automatically build tuning and test sets for your model.

Create a model

When you've finished selecting your desired documents, click Create Model button to create your model and start training. You can see the status of your training, and details for all the models you've trained, in the Models tab.

For more details, visit Create a Model.

Analyze your model

Once your training has completed successfully, inspect the results. The BLEU score is one metric that indicates the quality of your translation. You can also manually compare the translations made with your custom model to the translations provided in your test set by navigating to the "Test" tab and clicking "System Results." Manually inspecting a few of these translations will give you a good idea of the quality of translation produced by your system. For more details, visit System Test Results.

Deploy a trained model

When you are ready to deploy your trained model, click the "Deploy" button. You can have one deployed model per project, and you can view the status of your deployment in the Status column. For more details, visit Model Deployment

Deploy a trained model

Swap deployed model

To swap a deployed model with another within a project click the "Swap" button displayed next to the desired model. During the swap process, the deployed model will continue to be available to serve translation requests.

Swap deployed model

Use a deployed model

Deployed models can be accessed via the Microsoft Translator Text API V3 by specifying the CategoryID. More information about the Translator Text API can be found on the API Reference webpage.

Next steps