You probably have been using the Microsoft Language Portal website to lookup strings for your apps for a while now - I know that I have!  What you may not know is that a little while back Palle's team in the Microsoft Language Services group created the Terminology Service API to access these resources directly.  (Learn more in Palle’s blog ‘Announcing the Microsoft Terminology Service API’.)

You probably also noticed that the Multilingual App Toolkit has incorporated the Terminology Service since v2.0 via the Microsoft Language Portal Provider. This provider connects you directly to these resources from within the Multilingual Editor (and Visual Studio) just like it does with machine translations via the Microsoft Translator service.  But did you know that you can tune the service to your specific needs, such as specifying which products or product versions are returned?

In this blog, I’ll show how you can tune the results to match your specific requirements.  It’s easy and may even help you find that perfect translation for your project!

The first thing you need to know is that the Microsoft Language Portal Provider configuration file lives at ‘%ALLUSERSPROFILE%\Multilingual App Toolkit\MicrosoftLanguagePortalProvider\LanguagePortalSettings.xml’.  Let’s open this file and see what’s inside.  Note: You will need to have administrator privileges to save any changes.

Here are the default contents of the configuration file.  Most of these elements align directly with the Terminology Service API parameters, and as such are self-explanatory.

<?xml version="1.0" encoding="utf-8" ?>
<LanguagePortal>
  <Translation>
    <Enabled>True</Enabled>
    <SearchOperator>Exact</SearchOperator>
    <TranslationSources>
      <TranslationSource>UiStrings</TranslationSource>
      <TranslationSource>Terms</TranslationSource>
    </TranslationSources>
    <UniqueResults>True</UniqueResults>
    <IncludeDefinitions>False</IncludeDefinitions>
    <Products />
  </Translation>
  <Suggest>
    <SearchOperator>Contains</SearchOperator>
    <TranslationSources>
      <TranslationSource>UiStrings</TranslationSource>
      <TranslationSource>Terms</TranslationSource>
    </TranslationSources>
    <UniqueResults>True</UniqueResults>
    <IncludeDefinitions>True</IncludeDefinitions>
    <Products />
  </Suggest>
  <ServiceOptions>
    <CacheRefreshDays>7</CacheRefreshDays>
    <ConnectionLimit>10</ConnectionLimit>
    <ConnectionTimeout>60</ConnectionTimeout>
  </ServiceOptions>
</LanguagePortal>

As you can see, the provider’s configuration is split into <Translation> and <Suggest> sections.  The values (for the most part) map directly to the Terminology Service API SDK documentation values.  Keeping the translate and suggest configurations separate allows the provider to tune the results base on the type of request.  This is something to keep in mind when tuning the provider’s configuration as translate will usually differ from those used when getting suggestions.

For this blog, we’ll focus on the tuning the products and product versions within the <Suggest> configuration so we can easily see the results in the Editor’s suggestion panel. 

By default the service uses all products to locate the best possible match.  However, if you wanted product specific strings from Windows, for example, you would simply expand the <Products /> node to reference Windows specifically.  The format is:

    <Products>
      <Product Name="Windows" /> 
   </Products>

But what if you wanted to use strings from Windows 7, Windows 8, Windows 8.1 as well as strings from Visual Studio 2013? In this case, you would simply add the version configuration as well.

    <Products>
      <Product Name="Windows">
        <Version Value="7"/>
        <Version Value="8"/>
        <Version Value="8.1"/>
     </Product>
      <Product Name="Visual Studio">
        <Version Value="2013"/>
     </Product>
   </Products>

Now all suggestions will be scoped to the specified products and product versions.  But what if you want to choose between the Windows and Visual Studio results returned from the suggestion request?  How would you know which is which?

To accomplish this, you will enable the service’s definition and terminology metadata feature.  While this configuration is already on, the configuration for insuring unique results obscures the metadata.  Disabling unique results will allow the service to deliver the metadata.  To set the results to non-unique, change the <UniqueResults> value from True to False.

    ...
    <UniqueResults>false</UniqueResults>
    ...

One quick note about non-unique results – if you don't scope the product list, you run the risk of maxing out your suggestions (defaults to 5, max of 20) with the same suggestion across multiple products or even the same product with multiple versions.

With the reconfigured system, open a XLF file in the Multilingual Editor. Selecting a resource in the ‘Strings’ tab and clicking the suggest button will result in a list of suggestions based on the specified products and product versions. At first the results look the same, but the metadata is discoverable by hovering over the provided suggestion.

For my example, I used the string “Menu Item”.  After selecting suggest, hover over the result to see the related metadata, which now includes Product Name and Version.

image

Translated result Visual Studio 2013 resources

image

Translated result from Windows 8.1 resources

Don't forget to set the configuration back to the default, or the configuration that works best for you.