String resources
A PythonPart can be localized. Translated strings can be get from both global as well as local resources.
-
Global resources
Translations for unspecific strings, like length or color are already delivered with ALLPLAN, so you don't have to translate them.
-
Local resources
Translated strings specific for your PythonPart must be provided in a separate XML file.
Local string resources
Local string resources is an XML file with a collection of pairs (each represented by an <Item> node):
- resource ID in the
<TextId>tag - translated string in the
<Text>tag
<?xml version="1.0"?>
<Element>
<StringTable>Allplan PythonParts string table</StringTable>
<Item>
<TextId>1001</TextId><!--(1)!-->
<Text>rot</Text>
</Item>
<Item>
<TextId>1002</TextId>
<Text>grün</Text>
</Item>
</Element>
- The
<TextId>must start with 1001!
To assign the file with a PythonPart, save the file as xxx_xyz.xml, where:
- xxx is the name of the PythonPart .pyp file,
- xyz is the code of the language, which the file is intended for (e.g., deu for the file with German string resources)
The file must be located in the directory of PYP file (learn more about file locations here)
If a file with the current country code is not available, the xxx_eng.xml file is used instead. Information about missing string resource files and string resources are displayed in the ALLPLAN trace window.
Tip
It is possible to define different location of .xml file with string resources e.g., if you want to provide
one file for several PythonParts. In this case the file name and path must be defined in the .pyp file
in the <LanguageFile> tag (see here).
Include language file
If several PythonParts use the same texts, it might be more effective to define these texts only once
in a general language file and then include this file in the language file of the
individual PythonParts. This can be done using the tag <IncludeLanguageFile>
<?xml version="1.0"?>
<Element>
<StringTable>Allplan PythonParts string table</StringTable>
<IncludeLanguageFile>GeneralLanguageFile</IncludeLanguageFile>
<Item>
<TextId>1001</TextId>
<Text>Hallo</Text>
</Item>
...
</Element>
Global string resources
In addition to the local resource file of the PythonPart there is a global resource file with common strings located here:
..\etc\PythonPartsFramework\GeneralScripts\Stringtable\BuildingElement_lang.xml
The existing common string resources can be taken from this file. Unlike local resources, their IDs are strings, and have the format e_XXX e.g., e_LENGTH.
Accessing string resources
In PYP file
Each node in the PYP file with a <Text> tag can be provided with the <TextId> tag to localize this text.
The <TextId> tag contains then the reference to translated string.
To access a translated string from local string resources, provide its ID (integer) defined in the XML file:
To access a translated string from global string resources, provide its name from the XML file:
<Parameter>
<Name>String</Name>
<Text>Length</Text>
<TextId>e_LENGTH</TextId>
<Value>10.0</Value>
<ValueType>Double</ValueType>
</Parameter>
Alternatively, you can also use standard IDs defined internally in ALLPLAN. To do this, provide an option from a dedicated enumeration class. They are available in the AllplanSettings module and their names begin with TextRes. E.g. TextResSillType contains IDs pointing to texts about window sill types available in ALLPLAN.
Info
The <Text> tag is not the only one, that can be localized. For each node in the PYP file, we provide
the localizing instructions in the article about this node. For example
here you can learn how to localize
a <Parameter> node.
In script
To access both local and global string resources directly in the script, use the member function get_string_tables(), which returns a tuple containing the local and the global string table as a BuildingElementStringTable. A string resource can be then accessed by calling get_string().
graph LR
A[build_ele] --> B{{get_string_tables}};
B --> C[local_str_table];
B --> D[global_str_table];
C --> E{{get_string}};
D --> E;
E --> F[String];(local_str_table, global_str_table) = build_ele.get_string_tables()
msg_text = local_str_table.get_string("1001", "This is a message") #(1)!
- The second argument is the default string, used in case if the ID is missing in the resource file. In this case a warning would also be printed in the ALLPLAN trace window.