Using Yireo BingTranslate for Magento

The Yireo BingTranslate module allows you to easily implement the Microsoft Translation API into the Magento Admin Panel. Instead of adding the translation every time at the frontend, this extension allows you to store the translation in your backend. This tutorial shows you what you should do to implement Yireo BingTranslate into your site.

Get your API key from Microsoft Azure

The Microsoft Translation API (formerly known as the Bing Translate API) is an online service offered by Microsoft, and it can be used on any site - with only the requirement to apply for a API key. The API key can be applied for by creating an app under your Windows Azure account. First login to Windows Azure. During the registration you will need to enter a phonenumber (needed for SMS or voice verification) and a creditcard number. The translation API is free up to a certain amount. Once you have registered open up your Azure dashboard via the URL https://portal.azure.com/.

bingtranslate azure01

By default, the dashboard will be empty. Click on Create New. This pops up a new window with a search option. Search for Cognitive Services API. Once you have found this service, click on it, which will open up a new window.

bingtranslate azure02

In the new Create window, enter a new Account Name (whatever). Pick your Subscription - it should list a free tier as well. As API type, select the Translator Text API. As Pricing Tier, you should pick the F0 tier. Create a new Resource group. As Resource group location you can pick a location near you. Optionally, select the option Pin to Dashboard. Finally, hit the button Create. Now your app is created.

These steps are also documented here: http://docs.microsofttranslator.com/text-translate.html

bingtranslate azure03

Copy your key

Within the app within the Windows Azure environment, copy your key. The Microsoft documentation can be confusing at this point because they mix the words subscription ID and key a lot. Within your app window, you can find a tab Keys on the left (under Resource Management). Its contents show a Key 1 and a Key 2. You can pick either one of them. You don't need to pick both.

Get the Yireo BingTranslate module

The Yireo BingTranslate module is for sale on our site. Once purchased, you can download the latest version of this extension at any time by navigating to your Yireo Account. The extension is only available in the form of a ZIP file and is not available through the MagentoConnect downloader.

Installing the Yireo BingTranslate module

Download the ZIP file to your computer, extract all files and upload those files to the Magento root folder using FTPS or SSH. The ZIP file contains the following folders which correspond with existing folders in Magento:

  • app/etc/modules
  • app/code/community
  • app/design/adminhtml/base/default/layout
  • app/design/adminhtml/base/default/templates
  • skin/adminhtml/default/default

This extension does not modify your Magento frontend.

Refresh Magento caching

After uploading these files and folders to Magento, refresh the Magento cache. You can either do this from the Magento backend (System > Cache Management). You could also remove the entire var/cache folder through FTPS or SSH to remove the cache manually - an option that works often better than the Magento backend.

Don't forget to configure your locales

When setting up Magento for usage with multiple languages, part of that setup is to create Store Views per language. Do not forget to configure the System Configuration so that that specific Store View has the right locale set. For instance, if you create a Store View with a name Italian, there's nothing in Magento that guarantees that an Italian translation should actually be made for that specific Store View. Within the System Configuration, change the scope in the top left to the Store View named Italian. Next, under General > Locale Options change the Locale to Italian (Italy).

Warning on translating attributes

Make sure to take note that every product attribute is assigned to a specific scope. For instance, an color attribute can be assigned to the Store View scope. This means that you can manage the colour value of a product on the global level, but also override this value on the Store View level. However, take for instance the sku attribute, which is assigned to the Global scope. This makes it impossible to override this value in the Store View level. While editing a product, you might be able to switch to the Store View level and modify the SKU. However, the [GLOBAL] right from the input indicates that you will be modifying the attribute globally, across all scopes, across all Store Views.

This mentioning of how attributes work with scopes is not related to our extension but to Magento itself. If this is new to you, you might be missing out on more important hints about the Magento architecture. Make sure to take the time to go through the official Magento documentation.

Configuring the BingTranslate settings

Next, login to the Magento Admin Panel and browse to System > Configuration. Select the right scope (Store or Store View) to configure. Then navigate to Catalog > Catalog > Microsoft Translate. If this menu-option is not available, log out from the Magento Admin Panel and log back in again.

Within the configuration panel, you will need to configure the Subscription Key as generated on the Windows Azure website (see above). As soon as you have entered correct API key here, Bing Translate will be enabled in your backend.

googletranslate_04

Detecting the language

The Magento extension detects automatically the right languages: The language of the parent scope (the original text), and of the current scope (the translation). It also tries to detect whether the current text (in the current language) is already translated or not.

Original text (English)

googletranslate_02

Translated text (German)

googletranslate_03

Changing the button format

You can change the format of the button label, making it easier to understand what the module is doing. For instance, to see both the source language as well as the destination language, you can enter the following format:

Translate from $FROM to $TO

This will print for instance:

Translate from English to French

Why is the button greyed out?

A translation is always based on a source language and a destination language. The translate-button will be greyed out automatically when the locale/language of the current scope (either Global, Website or Store View) is matching the original scope.

  • When you enter the Products overview in the Magento backend, the scope is set to Global. The scope-selection is set to Default values. Because there is no point in translating the default language to the default language, the buttons are greyed out.
  • When you change the scope to a Store View called English, which has the US/English locale configured for it, but when the US/English locale is also the default locale, again the same applies: It makes no sense to translate English to English.
  • When you change the scope to a Store View called French, which has the French locale configured for it, while the default locale is English, then a translation is possible: The button will be usable because the text can be translated from English to French.

Supporting languages

On the following site, you can find a listing of languages (plus their language-codes) that are supported by the Bing translation services. If a language that you want to have translated, is missing in this list, there's little we can do: http://msdn.microsoft.com/en-us/library/hh456380.aspx

In some cases, the language-code offered by Magento (or actually the Zend Framework) differs from the language-code being asked by Bing. A good example is Chinese. Zend Framework delivers the language-code zh_CN (which is stripped to zh by this Yireo extension). However, Bing only understands the code zh-CHS.

In this case, manual configuration of the language-code is needed. Within the Magento backend, browse to the System Configuration and open up the section Catalog > BingTranslate. Make sure you choose the right scope (either the right Store or the right Store View). Enter as Manual language code the code listed by Bing.

bingtranslate langcode

Batch processing of products

Within the Manage Products overview of Magento, you will find that the Actions drop-down in the upper right, now also contains an option Translate via BingTranslate. Once you select products in the grid, you can use this batch action, which will bring you to a separate confirmation page. This confirmation page will confirm to you the batch translation of products.

Note that to use the batch processing properly, you also have to configure the extension options in the System Configuration: You will need to configure which product attributes and which Store Views will be used for batch processing.

Bork mode

Instead of using the Microsoft Translate API for translation, you can use Bork mode to generate fake strings. Bork is the language of the Swedish Chef from the Muppet show - check YouTube for details. The Bork mode can be enabled by entering bork as Subscription Key, or by setting its flag within the System Configuration.

Scripted usage of BingTranslate

By using the Magento code API you can apply BingTranslate for automated translations. The guide Automating Magento translations with BingTranslate gives you various code-samples to work with.

Troubleshooting: Translation API stops randomly

When the API seems to work sometimes, but sometimes it doesn't, it might be that the account key has expired for some reason. Microsoft seems to use several servers to check the key, and some of them might object. To fix this, it is easiest to apply for a new key and configure that new key in the Magento backend.

Keys handed out before March 2011 seem to be totally expired. For other keys, it counts that you need a secure key, instead of an insecure key. Because there is no indication about secure or insecure on the Windows Azure Marketplace, you might just try to generate a new key.

Troubleshooting: Azure Market Place Translator Subscription [...] has zero balance

You might receive a popup with the message The Azure Market Place Translator Subscription associated with the request credentials has zero balance. This simply means that you have exceeded the maximum amount of characters that you have subscribed for. Either wait for the next period or upgrade the subscription.

Migrating to Yireo BingTranslate 4

  • Tab BingTranslate is now called Microsoft Translate
  • Instead of Client ID and Client Secret, there is now only a Subscription Key
  • The extension now also includes a lib/Yireo folder with common libraries