Translate (XSIUtils)

Introduced

4.2

Description

Looks up a string in the specified Softimage dictionary and returns the corresponding string in the other language.

Softimage has a concept of a translation dictionary, which is a table of strings that have been translated from English into one or more other languages. Each translation dictionary is represented by a file in the factory/Application/Dictionary/en directory, with a .dict extension. When one of these dictionaries is translated into another language, a file with the same name is created in a directory named after the language. For example japanese translations are stored in the jp directory.

Each string can be referenced by its numeric ID or by providing the English version of the string.

Often a string needs to contain data that is very specific to the circumstance. For example if an error message was "File c:\temp\myfile.txt not found" then it would be impossible to translate every possible filename in the dictionary. In these cases the dictionary may use the %s token which represents a placeholder for up to three strings that you supply (via the String1, String2, and String3 arguments).

The number of %s tokens must exactly match the number of optional strings provided, up to a maximum of three. Other format tokens like %d are not supported and could result in a crash if they are present.

For example, instead of using "File c:\temp\myfile.txt not found", the dictionary string should take the format "File %s not found" so that when Translate method is called, the filename is specified using the String1 argument (see the 'warningMsg' example below).

Scripting Syntax

XSIUtils.Translate( Key, Dictionary, [String1], [String2], [String3] )

C# Syntax

String XSIUtils.Translate( Object in_ToTranslate, String in_Dictionary, String in_string1, String in_string2, String in_string3 );

Parameters

Parameter	Type	Description
Key	String or Integer	When a string is passed the English dictionary is searched to find the exact match and, if found, the equivalent in the current language dictionary is returned. If the string is not found then the provided string is returned. If the current language is English then it will always return whatever string was passed. It is also possible to provide the numeric id of the string in the dictionary. In this case it will go directly to the dictionary of the current language and attempt to find the string. If it does not find a string by that ID an empty string is returned.
Dictionary	String	Name of the dictionary to search. Dictionary names match the filename without the .dict extension.
String1	String	Optional argument to match the first %s in the string in the dictionary.
String2	String	Optional argument to match the second %s in the string in the dictionary.
String3	String	Optional argument to match the third %s in the string in the dictionary.

Return Value

String

Examples

JScript Example

// Demonstration of XSIUtils.Translate

currentLang = GetValue("Preferences.General.language") ;

Application.LogMessage( "The current language is " + currentLang ) ;

// You can't translate any arbitrary string, only
// ones that are already in the dictionary.

pixelRatio = XSIUtils.Translate( "Pixel Ratio", "XSIXSI" ) ;
Application.LogMessage( "Pixel Ratio translated is " + pixelRatio ) ;

// Load a Softimage warning message, in English
// it says "Do you want to remove it?"

errorMsg = XSIUtils.Translate( 333, "XSIMSGCAT" ) ;
XSIUIToolkit.MsgBox( errorMsg ) ;

// This is an error message that contains additional
// context information

// Dictionary contains: "31$Path %s has been changed to %s"
// Resulting string is:
// WARNING : 31$Path C:\out.txt has been changed to C:\temp\out.txt

warningMsg = XSIUtils.Translate(32, "XSIMSGCAT", "C:\\out.txt", "C:\\temp\\out.txt" );
Application.LogMessage( warningMsg, siWarning ) ;

See Also

siPPGLayoutAttribute

Autodesk Softimage v7.5