IDSSMultilingualString Interface Reference

List of all members.

---

Detailed Description

This interface represents a multilingual string.

A multilingual string is a mapping from locale ids to strings that represent translations of the string in that locale. Each translation has a boolean flag which is used to indicate whether a particular translation has been validated. The semantics of validation are application specific. Multilingual strings' behavior depends on two context dependent locale ids. The effective locale id is the locale which will be used if the user does not specify an explicit locale id. The primary locale id is the locale to which the implementation will fall back if no translation is available in the explicitly provided locale or implicitly deduced effective locale. Neither the effective locale id nor the primary locale id are stored on the multiligual string itself but come from an object or an object source.

Public Member Functions
HRESULT	Clear ()
	Remove all translation strings from this instance.
HRESULT	EffectiveLocale ([out, retval] Int32 *opLocale)
	Return the effective locale of this multilingual string.
HRESULT	EffectiveTranslation ([in] BSTR iTranslation)
	Set the translation string for the effective locale id of the governing object.
HRESULT	EffectiveTranslation ([out, retval] BSTR *opTranslation)
	Get the translation string for the effective locale id of the governing object.
HRESULT	ExcludeFromIteration ([out, retval] VARIANT_BOOL *opExcludeFromIter)
HRESULT	HasTranslation ([in] Int32 iLocale,[in] VARIANT_BOOL iHasTranslation)
	If iHasTranslation is VARIANT_FALSE and a translation exists for locale id iLocale, remove the existing translation.
HRESULT	HasTranslation ([in] Int32 iLocale,[out, retval] VARIANT_BOOL *opHasTranslation)
	Return a flag indicating whether or not a translation string is available for the given locale id.
HRESULT	HumanReadableKey ([in, optional, defaultvalue(0x0400)]Int32 iLocale,[out, retval] BSTR *opKey)
	Get the human readable string containing the semantic tags of the nodes in the key that uniquely identifies the multilingual string within the object instance that contains it.
HRESULT	Info ([out, retval] IDSSObjectInfo oppObjectInfo)
	Get the instance of the object from which this multilingual string came from.
HRESULT	Key ([out, retval] BSTR *opKey)
	Get the string representing the key that uniquely identifies the multilingual string within the object instance that contains it.
HRESULT	Populate ([in] IDSSMultilingualString *ipMultilingualString)
	Populate the contents of this instance from another.
HRESULT	PrimaryLocale ([out, retval] Int32 *opLocale)
	Return the primary locale of this multilingual string.
HRESULT	PrimaryTranslation ([in] BSTR iTranslation)
	Set the translation string for the primary locale id of the governing object.
HRESULT	PrimaryTranslation ([out, retval] BSTR *opTranslation)
	Get the translation string for the primary locale id of the governing object.
HRESULT	SemanticTagKey ([out, retval] BSTR *opKey)
	Get the string containing the semantic tags of the nodes in the key that uniquely identifies the multilingual string within the object instance that contains it.
HRESULT	Translation ([in] Int32 iLocale,[in] BSTR iTranslation)
	Set the translation string for the given locale iLocale.
HRESULT	Translation ([in] Int32 iLocale,[out, retval] BSTR *opTranslation)
	Get the translation string for the given locale iLocale.
HRESULT	TranslationCount ([out, retval] Int32 *opCount)
	Return the number of locales for which a translation string is available.
HRESULT	TranslationLocale ([in] Int32 iIndex,[out, retval] Int32 *opLocale)
	Return the locale id of the translation string at the given index.
HRESULT	TranslationString ([in] Int32 iIndex,[out, retval] BSTR *opString)
	Return the text of the translation string at the given index.

---

Member Function Documentation

HRESULT IDSSMultilingualString::Clear (   )

Remove all translation strings from this instance. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::EffectiveLocale (  [out, retval] Int32 *  opLocale  )

Return the effective locale of this multilingual string. The effective locale determines which translation will be set or returned when the caller calls the EffectiveTranslation method. The effective locale is calculated as follows. If the string contains a translation in the effective locale of the object source of the object that contains this string, return this locale. Otherwise, return the primary locale as calculated by IDSSMultilingualString::PrimaryLocale. The effective locale of the object source is the result of mapping the metadata locale as obtained from IDSSSource5::MetadataLocale to a locale supported by the project or the configuration using IDSSLocales::MapToSupported. In legacy projects that do not support internationalization this method will return DssLocaleNeutral. Parameters: opLocale  The effective locale of this multilingual string. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::EffectiveTranslation (  [in] BSTR  iTranslation  )

Set the translation string for the effective locale id of the governing object. The translation will be marked as validated. All other translations will be marked as not-validated. Parameters: iTranslation  The translation string for the effective locale id. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::EffectiveTranslation (  [out, retval] BSTR *  opTranslation  )

Get the translation string for the effective locale id of the governing object. Parameters: opTranslation  The translation string for the effective locale id. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::ExcludeFromIteration (  [out, retval] VARIANT_BOOL *  opExcludeFromIter  )

HRESULT IDSSMultilingualString::HasTranslation (  [in] Int32  iLocale, [in] VARIANT_BOOL  iHasTranslation )

If iHasTranslation is VARIANT_FALSE and a translation exists for locale id iLocale, remove the existing translation. If iHasTranslation is VARIANT_TRUE and no translation exists for locale id iLocale, add an empty translation. The DssLocalePrimary and DssLocaleEffective locale ids are supported. Parameters: iLocale  The locale id for which the caller wants to add or remove a translation. iHasTranslation  A flag indicating whether the caller wants to add or remove a translation for the given locale id. Returns: Usual COM result code: S_OK DSSCOM_E_UNSUPPORTED_LOCALE The caller asked to add or remove a translation for a locale that is not supported by the project or the configuration.

HRESULT IDSSMultilingualString::HasTranslation (  [in] Int32  iLocale, [out, retval] VARIANT_BOOL *  opHasTranslation )

Return a flag indicating whether or not a translation string is available for the given locale id. Passing in DssLocalePrimary will return a flag indicating whether a translation string is available for the primary locale. Passing in DssLocaleEffective will return a flag indicating whether a translation string is available for the effective locale. Parameters: iLocale  The locale id for which the caller wants to know if a translation string is available. opHasTranslation  VARIANT_TRUE if a translation string is available for locale with id iLocale, VARIANT_FALSE otherwise. Returns: Usual COM result code: S_OK DSSCOM_E_UNSUPPORTED_LOCALE The caller asked if a translation is available for a locale that is not supported by the project or the configuration.

HRESULT IDSSMultilingualString::HumanReadableKey (  [in, optional, defaultvalue(0x0400)] Int32  iLocale, [out, retval] BSTR *  opKey )

Get the human readable string containing the semantic tags of the nodes in the key that uniquely identifies the multilingual string within the object instance that contains it. Unlike the key string, the human readable key is not guaranteed to be unique and cannot be used to retrieve this multilignual string. Its format may change between releases. It is only intended to be used for information purposes like aiding the translator in the process of translation. Parameters: iLocale  The locale to be used for the key to be returned. opKey  The human readable version of the semantic tag key of the multilingual string. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::Info (  [out, retval] IDSSObjectInfo   oppObjectInfo  )

Get the instance of the object from which this multilingual string came from. Parameters: oppObjectInfo  The instance of the object from which this multilingual string came from. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::Key (  [out, retval] BSTR *  opKey  )

Get the string representing the key that uniquely identifies the multilingual string within the object instance that contains it. The caller who has this string and can identify the object the string came from can use it to retrieve this multilingual string by passing the key into the IDSSGenericData::MultilingualString method. The API guarantees to maintain backwards compatibility for all key strings. Parameters: opKey  The string representing the key that uniquely identifies the multilingual string within the object instance that contains it. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::Populate (  [in] IDSSMultilingualString *  ipMultilingualString  )

Populate the contents of this instance from another. Parameters: ipMultilingualString  The instance from which to populate this one. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::PrimaryLocale (  [out, retval] Int32 *  opLocale  )

Return the primary locale of this multilingual string. The primary locale is calculated as follows. If the object containing this multilingual string has a primary locale set, return this locale. Otherwise, if the object is embedded and the container has a primary locale set, return this locale. Otherwise, return the primary locale of the project or configuraion that contains the object that in turn contains this multilingual string. In legacy projects that do not support internationalization this method will return DssLocaleNeutral. Parameters: opLocale  The primary locale of this multilingual string. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::PrimaryTranslation (  [in] BSTR  iTranslation  )

Set the translation string for the primary locale id of the governing object. The translation will be marked as validated. All other translations will be marked as not-validated. Parameters: iTranslation  The translation string for the primary locale id. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::PrimaryTranslation (  [out, retval] BSTR *  opTranslation  )

Get the translation string for the primary locale id of the governing object. Parameters: opTranslation  The translation string for the primary locale id. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::SemanticTagKey (  [out, retval] BSTR *  opKey  )

Get the string containing the semantic tags of the nodes in the key that uniquely identifies the multilingual string within the object instance that contains it. Unlike the key string, the semantig tag key is not guaranteed to be unique and cannot be used to retrieve this multilignual string. Parameters: opKey  The string representing the semantic tag key of the multilingual string. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::Translation (  [in] Int32  iLocale, [in] BSTR  iTranslation )

Set the translation string for the given locale iLocale. iLocale must come from the set of locale ids supported by the project or configuration that contains the governing object. The translation will be marked as validated. All other translations will be marked as not-validated. Passing in DssLocalePrimary will set the translation for the primary locale and is equivalent to calling PrimaryTranslation. Passing in DssLocaleEffective will set the translation for the effective locale and is equivalent to calling EffectiveTranslation. Passing in NULL or an empty string for iTranslation have the effect of removing the translation, if any, for locale id iLocale. Parameters: iLocale  The locale for which the caller wants to set the translation. iTranslation  The translation string for the given locale. Returns: Usual COM result code: S_OK DSSCOM_E_UNSUPPORTED_LOCALE The caller asked to set a translation for a locale that is not supported by the project or the configuration.

HRESULT IDSSMultilingualString::Translation (  [in] Int32  iLocale, [out, retval] BSTR *  opTranslation )

Get the translation string for the given locale iLocale. iLocale must come from the set of locale ids supported by the project or configuration that contains the governing object. If no translation exists for the given locale the translation for the primary locale of the governing object will be returned. Passing in DssLocalePrimary will return the translation for the primary locale and is equivalent to calling PrimaryTranslation. Passing in DssLocaleEffective will return the translation for the effective locale and is equivalent to calling EffectiveTranslation. Parameters: iLocale  The locale for which the caller wants to get the translation. opTranslation  The translation string for the given locale. Returns: Usual COM result code: S_OK opTranslation has been set to the string of the translation for the given locale id S_FALSE opTranslation has been set to the string of the primary translation DSSCOM_E_UNSUPPORTED_LOCALE The caller asked to get a translation for a locale that is not supported by the project or the configuration.

HRESULT IDSSMultilingualString::TranslationCount (  [out, retval] Int32 *  opCount  )

Return the number of locales for which a translation string is available. Parameters: opCount  The number of locales for which a translation string is available. Returns: Usual COM result code: S_OK

HRESULT IDSSMultilingualString::TranslationLocale (  [in] Int32  iIndex, [out, retval] Int32 *  opLocale )

Return the locale id of the translation string at the given index. The first translation string has index 1. Parameters: iIndex  The index of the translation string for which the locale id is desired. opLocale  The locale id of the translation string at index iIndex. Returns: Usual COM result code: S_OK E_INVALIDARG iIndex is less than one or greater than the number of translation strings.

HRESULT IDSSMultilingualString::TranslationString (  [in] Int32  iIndex, [out, retval] BSTR *  opString )

Return the text of the translation string at the given index. The first translation string has index 1. Parameters: iIndex  The index of the desired translation string. opString  The text of the translation string at index iIndex. Returns: Usual COM result code: S_OK E_INVALIDARG iIndex is less than one or greater than the number of translation strings.

---