Language translations

Overview

Survey Core contains systems for displaying strings to users in their language of choice.  These systems are available to the plugin programmer, who may make use of the several thousand Survey Core strings that are already translated, and he may provide additional strings and translations for those strings peculiar to his plugin.

Strings are referenced by the plugin programmer by using x_Codes.  An x_Code is simply an enumeration (i.e. an integer) that represents the string. 

Existing Survey Core strings are accessed by passing an x_Code to the tsc_SurveyCore::Translate() method.  A string in the user's currently selected language is returned, or in one of the fallback languages if a translation is not present.  A Survey Core x_Code may also be used in any API method that takes an x_Code as a parameter.

All available Survey Core strings have an x_Code defined in the header file Include\sc_XCodes.h in the SDK, and all of these definitions consist of "X_" followed by the name of the string which usually reflects the content of the string itself, for example:

enum x_Code : int

{

    ...

    X_NewStationSetupRequired    = 3618,
    ...
};

To find an existing Survey Core translation, look through the ...\include\sc_xcodes.h header. The token names in this file generally reflect the English text, but that's not necessarily the case. Bear in mind that Trimble may delete translations that are no longer in use in Trimble Access. We have no way of knowing which x_codes are used by plugins so beware of x_codes disappearing from the enumeration. If this occurs, the token name is used as the translation.

Custom plugin translations

A plugin may supply its own translations in an XML file.  Such a file is known as a Translation Database and has a .tdb extension.  This TDB file is installed on the user's device when the plugin is installed.  The TDB file is placed in the same directory as the plugin library (.dll or .so), and it is loaded when the plugin is initialized.

The TDB file and the necessary build steps are automatically generated when the Visual Studio Template wizard is used to create the plugin project.  The build step creates a header file (<pluginName>_XCodes.h) that is included into the plugin project.  This header file contains a definition for each string identifier in the TDB file with PX_ prepended, so for example, if the TDB file contained a string with the identifier AnotherStationSetupRequired, the header file would contain a definition similar to the following:

#define PX_AnotherStationSetupRequired   (x_Code)100002

The plugin may then obtain the string translated into the current language by calling the translation method:

tsc_SurveyCore::Translate (PX_AnotherStationSetupRequired);

The x_Code may be used in any API method that takes an x_Code as a parameter, such as:

tsc_SurveyCore::StatusMessage (PX_AnotherStationSetupRequired);

It is important to always rebuild the plugin after modifying the TDB file. The project dependencies are such that this will usually happen automatically. The build step runs the command line utility ApiLanguageTool.exe which creates a new header file (<pluginName>_XCodes.h) and reassigns the x_Code values based on the content of the TDB file. Any mismatch between the .tdb file and the header will result in the displayed strings being incorrect.

When a customer uses a plugin application, the language they have configured in Trimble Access will be chosen from the .tdb file.  If no translation is found for an x_Code, the base language translation is used (if present), otherwise the English translation is used, and failing all else the token name is used for the translated string.

Help file integration

Plugin developers can integrate their help content with Survey Core if they wish to.  Each TDB based x_Code can be flagged as a help topic title by having a help URL associated with it.  When help is requested in the plugin application a list of help topics is generated from the nominated x_Code entries in the TDB file.

The help URL itself is a free form string which Trimble Access will attempt to execute when it is selected.  We suggest using locally installed html files suitable for display on mobile devices.

Use the tsc_Path macros (which includes language) to specify a suitable locations, for example:
$(PluginResDir)/Help/$(IsoLanguage)/$(IsoLanguage)_TopicFileName.htm
Both kinds of slash (/ or \) will work.

When a help file is not available in the current language, the language defaults to the TDB file base language.

Note: When debugging/developing a plugin, the location will be different to the normal user's install location, however the $(PluginResDir) path macro will always resolve to the correct directory.

Note that local File paths that include an anchor (#name) do not always work well with desktop browsers.

It is possible to set a help topic x_Code on a form (see tsc_Form) so that when help is requested the correct topic is pre-selected for the user.

Translation management tool

A translations tool will be installed into the SDK tools directory along with the SDK.  It is called TransIt (TransItApp.exe).  Run this program and open the file pluginName.tdb to add or edit string translations.  TransItApp.exe may also be run with the name of the .tdb file on the command line.

To add translations, choose Add Translation Unit from the Edit menu and fill in the identifier, the English (or your base language), and the comment. The identifier should be as similar as possible to the string itself.  For instance the identifier (token name) for the string "More station setups are required" should be something like MoreStationSetupsRequired.

A comment is required; this is used to inform the translator and future programmers what the word or phrase means.  This field cannot be blank, which forces you to think about the meaning.  For instance, the word Close has at least two meanings in English - it can mean Shut as in "Close the file", or Near as in "Close to this position", but in many other languages Close has two very different translations and the translator must be informed which one is required. A programmer who is using the translation also needs to know the usage of the word before reusing it in some other part of the plugin.

Remember to save the file before exiting (you'll be prompted).  After editing the file, rebuild the plugin to pick up the new strings.

Technical details

This section may be skipped unless there are particular requirements not covered by the Visual Studio template wizard, or if you wish to gain a greater understanding of the translations system.

The TDB format is XML and quite straightforward; each string is defined in a translation unit, with an identifier, plus a number of translations in various languages.  The identifier corresponds to the x_Code name.  About 35 languages are supported by Survey Core.  

The TDB file is expected to use utf-8 encoding.

A small TDB file might look like this:

<?xml version="1.0" encoding="UTF-8"?>

<language.database.utf8 tdb-version="1.0">

   <id>General Survey v1.60</id>

   <base.language>de</base.language>

   <sort.by.base.language>True</sort.by.base.language>

   <translation.unit id="NewStationSetupRequired"

          help-url="$(PluginResDir)/Help/$(IsoLanguage)/$(IsoLanguage)_NewStnSetupReq.htm">

      <en>A new station setup is required</en>

      <fr>Une nouvelle config. de station est requise</fr>

      <de>Eine neue Stationierung ist erforderlich</de>

      <es>Se requiere una nueva configuración de estación</es>

      <pt>Requer-se nova configuração da estação</pt>

      <zh-CHS>需要新的测站设立</zh-CHS>

      <sk>Je požadované nové určenie stanoviska</sk>

      <sl>Potrebno je ponovno definirati stojisce</sl>

   </translation.unit>

   <translation.unit id="ConfirmDeletion">

      <comment>Confirm deletion of files</comment>

      <en>Confirm deletion</en>

      <fr>Confirmer suppression</fr>

      <de>Löschen bestätigen</de>

      <es>Confirme eliminación</es>

      <pt>Confirmar deleção</pt>

      <zh-CHS>确认删除</zh-CHS>

      <sl>Potrdi brisanje</sl>

   </translation.unit>

</language.database.utf8>

A plugin can load the TDB file by specifying the tdb path string in the tsc_RegisterPlugin function. The filename is relative to the directory containing the plugin; if the TDB file is always placed in the same directory then only the name is required as a parameter. An absolute path is not recommended due to platform differences.

Choosing which language translation to use

The end-user chooses which language he or she wishes to see, by using the Trimble Access settings application.  The languages listed for the user to choose are the ones that have been installed for Trimble Access (i.e. Survey Core).  This means a plugin cannot support a language that is not supported by Survey Core. The language chosen by a user is not necessarily present in a plugin's TDB file, so a series of fallbacks are used.

When looking up a translation identifier (x-code), Survey Core searches for a suitable language in the following order:

1. 1. If the user's currently selected language is present for the identifier, that translation is used.

   2. Otherwise, if a <base.language> tag is found in the TDB file and a translation for that language is present, it is used.

   3. Otherwise, if no <base.language> tag is found, and an English translation is present, it will be used.

   4. Otherwise, the first language string for the identifier in the TDB file is used, regardless of the language.

   5. Otherwise (as a last resort when no translations are present) the identifier itself is used.

Build tools

A number of language tools are available to make string editing and translations user-friendly.

One of these tools, ApiLanguageTool.exe, is designed to run as a build step, perhaps as part of a Microsoft Visual C++ project.  This tool reads the TDB file and produces a header file which defines each identifier as a unique number called the x_Code.  These numbers start at 100000 to distinguish them from the Survey Core built-in x_Codes which range from 1 to about 1100. 

The generated header file may look something like this:

/* 

* Trimble(R) Survey Core API : Plugin custom language string name definitions
* This file was derived from TDB file: c:\Dev\Survey Core\Trunk\Plugins\TestScApi\TestScApi.tdb  At 26/06/2010 6:32:12 p.m.
* This file is automatically generated and must match the .tdb file: =====| DO NOT EDIT |===== 

*/
#define PX_NewStationSetupRequired  (x_Code)100000
#define PX_ConfirmDeletion          (x_Code)100001 

This header (which is usually named pluginName_XCodes.h) may then be included into plugin modules to provide direct access to the translated strings by calling the tsc_SurveyCore::Translate() method, or simply by passing the x_Code to any other API function which takes an x_Code as a parameter.  For example:

tsc_SurveyCore::StatusMessage (PX_NewStationSetupRequired);

The "PX_" prefix is used to prevent clashes with the Survey Core x_Code names defined in x_Codes.h; it is configurable to any string and defaults to PX_.

Survey Core relies on an exact one-to-one mapping between the numbers in the Plugin_XCodes.h header file and the <token> tags in the TDB file.  If these two files are not kept in step then incorrectly displayed strings may result.  ApiLanguageTool should therefore be run as part of the plugin build process, and the same unedited TDB included into the installer file which installs the plugin.  In this way, they will always remain in step.

Configuring an MSVC project for translations

Note: The Trimble project wizard for Visual Studio will do much of the following for you automatically.

The build process can be made completely automatic with the following configurations:

• 1. Create a TDB file and add it to the plugin project.

  2. Add a custom build step on the TDB file (right click and choose Properties, then Custom build step).

  3. Add a Post Build event to the project to copy the TDB file to the same directory as the plugin library.

For example, the following should work for any project:

Custom build step command line:

"..\..\sc\ScApi\Tools\ApiLanguageTool.exe" /h "$(InputPath)" "$(ProjectDir)\Plugin_XCodes.h"

copy "$(InputPath)" "$(ProjectDir)$(PlatformName)\$(ConfigurationName)"

Set Custom build step outputs as follows (hint: click the drop-down list and choose edit):

$(ProjectDir)\Plugin_XCodes.h

$(ProjectDir)$(PlatformName)\$(ConfigurationName)\$(InputFileName)

Project properties -> Build Events -> Post-Build event:

xcopy "$(OutDir)\$(ProjectName).dll" "%AppData%\Trimble\Trimble Survey Core vx.yy API Plugins\YourSubdir\" /i /Y /F

xcopy "$(OutDir)\$(ProjectName).tdb" "%AppData%\Trimble\Trimble Survey Core vx.yy API Plugins\YourSubdir\" /i /Y /F

Other translation tools

TransItApp is a Windows tool for editing the translated string and adding new ones.  It has already been described above.