Kentico CMS 7.0 Developer's Guide

Creating machine services

Creating machine services

Previous topic Next topic Mail us feedback on this topic!  

Creating machine services

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

To develop a custom machine translation service, you need to define a class that inherits from AbstractMachineTranslationService (found in the CMS.TranslationServices namespace).


The service class must override and implement the following abstract methods:





The main translation method which calls the appropriate web service (Google, Bing etc.) or otherwise translates the specified text from the source language into a target language.


When a user submits a translation to the service, the system calls the Translate method for every translation unit (<trans-unit> element) in the XLIFF source data. The method's text parameter contains the source text of the unit.


You can use this method to call the logic of the translation service to automatically determine the language of the source text.


Kentico CMS does not use the Detect method by default, but you can implement it if you need language detection functionality in your custom API.


Converts text to a stream of sound using the given service's text-to-speech engine.


Kentico CMS does not use the Speak method by default, but you can implement it if you need text-to-speech functionality in your custom API. If your service does not support such an option, throw a not implemented exception.


Checks whether the service is appropriately configured and ready to be used. For example, you can confirm that the target service is currently online, or load any credentials and API keys required by the service from the website settings and confirm their validity.


The system only offers the service when translating documents and resource strings if the IsAvailable method returns a true value.


Defining machine service classes


This example demonstrates how to write a class providing functionality for a machine translation service. The sample class does not use a real translation service, it only converts the source text to upper case. When creating your own classes, replace the code of the methods with your own translation logic or call the API of the appropriate web service.


1. Open your web project in Visual Studio and add a new class into the App_Code folder (or Old_App_Code if the project is installed as a web application). For example, name the class SampleMachineTS.cs.


2. Edit the class and change its code to the following:




using System;
using CMS.TranslationServices;
using CMS.IO;

/// <summary>
/// Sample machine translation service.
/// </summary>
public class SampleMachineTS : AbstractMachineTranslationService
  /// <summary>
  /// Translates the specified text from the source language to the target language.
  /// Must return the translated text as a string.
  /// </summary>
  /// <param name="text">Text to translate</param>
  /// <param name="sourceLang">Source language culture code</param>
  /// <param name="targetLang">Target language culture code</param>
  public override string Translate(string text, string sourceLang, string targetLang)
      // "Translates" the text to upper case.
      return text.ToUpper();

  /// <summary>
  /// Automatically attempts to detect the language of the source text.
  /// Returns the culture code of the detected language.
  /// </summary>
  /// <param name="text">Text to be processed</param>
  public override string Detect(string text)
      // Use your service to detect the language. This example always returns English.
      return "en-US";

  /// <summary>
  /// Returns a stream of sound generated by text-to-speech services (if supported).
  /// </summary>
  /// <param name="text">Text to be processed</param>
  /// <param name="lang">Culture code of the text's language</param>
  public override Stream Speak(string text, string lang)
      // This service provider does not support Text-to-speech.
      throw new NotImplementedException();

  /// <summary>
  /// Checks the necessary prerequisities needed for the service to work,
  /// e.g. availability of credentials for connecting to the service etc.
  /// </summary>
  public override bool IsAvailable()
      // This sample provider does not require any settings and does not depend on
      // any other services, therefore is always available.
      return true;


The system calls the methods of the class as needed when the given translation service is used.


3. Follow the instructions in the Loading service classes from App_Code topic to ensure that the application can access the custom class.


Registering machine services in the system


Once you have implemented the class with the required functionality, you need to register the translation service as an object in Kentico CMS:


1. Go to Site Manager -> Development -> Translation services and click NewTranslationService New translation service.


2. Enter the following values into the service's properties:


Display name: Sample machine service

Code name: Leave the (automatic) option. The system will generate the code name as Sample_machine_service (based on the display name).

Service provider assembly name: App_Code

Service provider class name: SampleMachineTS

Is machine translation service: Yes (checked)

Service is enabled: yes (checked)


Click Save Save.


The service is now ready to be used.


Assigning icons to machine services


When editing resource strings for specific user interface cultures, users can translate the text from the default language by clicking on icons representing the available machine translation services. To set an icon for your custom service:


1. Open the \App_Themes\Default\Images\ folder in your web project.

2. Extract the CMSModules folder from the archive and place it into the \App_Themes\Default\Images\ directory.

3. Add the icon image file into the CMSModules\CMS_TranslationServices folder. The name of the file must match the code name of the given translation service, so use Sample_machine_service.png for this example. The recommended size for the icon is 16 x 16 px.


The system automatically loads the service icon images from this folder.




When submitting documents for translation, the dialog offers the Sample machine service as one of the translation service options. Using this option creates the new language version of the document as a copy of the original content, with all characters converted to upper case.


Submitting a document for translation using the sample machine service

Submitting a document for translation using the sample machine service


Users can also call the custom translation service when localizing resource strings.


"Translating" a resource string using the sample service

"Translating" a resource string using the sample service