Localization

Localisation

ZBrush 4R8 has localisation options so that users can choose how the ZBrush interface is displayed from a number of different languages. The ZFileUtils now allows users to add localisation to their plugins.

Warning!

ZBrush can only load ZScript TXT files as ANSI/ASCII encoding. This means that you cannot hard code Unicode strings, or include special characters for languages such as Japanese.

Translations for localisation are added to specially formatted XML files. The files must be named using the following form:

[name]en.xml (English)
[name]fr.xml (French)
[name]jp.xml (Japanese)
[name]es.xml (Spanish)
[name]de.xml (German)
[name]zn.xml (Chinese)
[name]ko.xml (Korean)

For example, the localisation files included with the ZFileUtils are for English and French and are named zfutils_en.xml and zfutils_fr.xml.

Editing the XML file

The first part of the XML file handles the interface items such as plugin palette, buttons, switches and sliders. These are grouped within the <buttons> tag.

<buttons>
  <button path="ZPlugin:ZFileUtilsTests">
    <title text="ZFileUtilsTests" trans="Tests de ZFileUtils"/>
  </button>
  <button path="ZPlugin:ZFileUtilsTests:Dropdown & Localisation:Rename SubTool">
    <title text="Rename SubTool" trans="Renommer le SubTool"/>
    <info text="Will rename the current SubTool with the name you've entered" trans="Renommer le SubTool courant avec le nom que vous avez entré"/>
  </button>
</buttons>

The button path applies to any of the interface items. The title text is the name of the button and the info text is the pop-up info.

Important!

The text for each of these must be exactly the same as in the plugin zscript code, otherwise the translation may fail.

Enter the translation for each button text after the trans= . Make sure to use double quotes around the whole string.

The second part of the XML file handles messages, grouped within the <messages> tag. These can be for pop-up messages when the plugin asks the user for input, or they can be used for input strings which can be retrieved by the plugin.

Each message has a tag so that it can be identified when needed during plugin operation. This must be made up of capital letters and underscores.

<messages>
  <message tag="ZFU_RENAME_SUBTOOL_CONFIRMATION">
    <info text="You are about to rename current SubTool as %arg1%.\nAre your sure you really want to name it %arg1%?" trans="Vous êtes sur le point de renommer le SubTool courant en %arg1%.\n Etes vous vraiment sûr de vouloir faire çà?"/>
  </message>
  
</messages>

Enter the translation for each message text after the trans= . Make sure to use double quotes around the whole string. The %arg1% can be used for specific text that is added at runtime, such as the new name of a subtool (as in the example zscript included in the ZFileUtils zip).

Localization Functions

Get current language

Function to get the current language.

- lang: the current language index

[RoutineDef, ZFU_GetCurrentLanguage,
	[VarSet, lang, [FileExecute, [Var, dllPath], GetCurrentLanguage]]
, lang]

Register localization files

Function to Register localization files for the plugin

- enFilePath: path to the english xml localization file, must be formated “[name]en.xml”
  other languages are deduced as being “[name]fr.xml”, “[name]jp.xml”, etc…

[RoutineDef, ZFU_RegisterLocalizationFile,
	[FileExecute, [Var, dllPath], RegisterLocalizationFile, enFilePath]
, enFilePath]

Localize text

Function to Localize a given text, tag or UI path

- text is in/out:
  – as an input, it is used to search for the localized item
  – as an output, it is replaced by the localized string
- text can refer to a tag, a UI path or be any untranslated text:
  – a tag: if it’s formated “#[tagname]”
  – a path: if it’s a valid path to a UI item
  – any text: if it’s not a tag nor a UI path, then it’s considered as an untranslated text

[RoutineDef, ZFU_LocalizeText,
	[If, [MemGetSize, ZFU_Mem_Temp],, [MemCreate, ZFU_Mem_Temp, 256]]
	[If, [FileExecute, [Var, dllPath], GetLocalizedText, text,, ZFU_Mem_Temp],,
		[MemReadString, ZFU_Mem_Temp, text]
	]
	[MemDelete, ZFU_Mem_Temp]
, text]

Localize Title

Function to Localize a given title

- text is in/out:
  – as an input, it is used to search for the localized item
  – as an output, it is replaced by the localized string
- text can refer to a tag, a UI path or be any untranslated title:
  – a tag: if it’s formated “#[tagname]”
  – a path: if it’s a valid path to a UI item
  – a title: if it’s not a tag nor a UI path, then it’s considered as an untranslated title

[RoutineDef, ZFU_LocalizeTitle,
	[If, [MemGetSize, ZFU_Mem_Temp],, [MemCreate, ZFU_Mem_Temp, 256]]
	[If, [FileExecute, [Var, dllPath], GetLocalizedTitle, text,, ZFU_Mem_Temp],,
		[MemReadString, ZFU_Mem_Temp, text]
	]
	[MemDelete, ZFU_Mem_Temp]
, text]

Localize info

Function to Localize a given info

- text is in/out:
  – as an input, it is used to search for the localized item
  – as an output, it is replaced by the localized string
- text can refer to a tag, a UI path or be any untranslated info:
  – a tag: if it’s formated “#[tagname]”
  – a path: if it’s a valid path to a UI item
  – a info: if it’s not a tag nor a UI path, then it’s considered as an untranslated info

[RoutineDef, ZFU_LocalizeInfo,
	[If, [MemGetSize, ZFU_Mem_Temp],, [MemCreate, ZFU_Mem_Temp, 256]]
	[If, [FileExecute, [Var, dllPath], GetLocalizedInfo, text,, ZFU_Mem_Temp],,
		[MemReadString, ZFU_Mem_Temp, text]
	]
	[MemDelete, ZFU_Mem_Temp]
, text]

Localize description

Function to Localize a given description

- text is in/out:
  – as an input, it is used to search for the localized item
  – as an output, it is replaced by the localized string
- text can refer to a tag, a UI path or be any untranslated descr:
  – a tag: if it’s formated “#[tagname]”
  – a path: if it’s a valid path to a UI item
  – a descr: if it’s not a tag nor a UI path, then it’s considered as an untranslated description

[RoutineDef, ZFU_LocalizeDescr,
	[If, [MemGetSize, ZFU_Mem_Temp],, [MemCreate, ZFU_Mem_Temp, 256]]
	[If, [FileExecute, [Var, dllPath], GetLocalizedDescr, text,, ZFU_Mem_Temp],,
		[MemReadString, ZFU_Mem_Temp, text]
	]
	[MemDelete, ZFU_Mem_Temp]
, text]

Replace argument

Function to replace argument in message text.

[RoutineDef, ZFU_StrReplaceArg,
	[If, [MemGetSize, ZFU_Mem_Temp],, [MemCreate, ZFU_Mem_Temp, 256]]
	[MemWriteString, ZFU_Mem_Temp, text]
	[If, [FileExecute, [Var, dllPath], StrReplaceArg, argText, argIndex, ZFU_Mem_Temp],,
		[MemReadString, ZFU_Mem_Temp, text]
	]
	[MemDelete, ZFU_Mem_Temp]
, text, argIndex, argText]