Joseph Doherty
32f26272ae
Five tools under one repo, all docs organized per DOCS-GUIDE.md: - aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands: last, tail, range, unread, fields. Stable JSON envelope under --llm-json. Build template under lib/build/ for rebuilding aaLogReader.dll. - aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide (Markdown converted from CHM), API reference for the ArchestrA.Toolkit namespace, and the Monitor / Watchdog VS sample solutions. - graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy configuration via the ArchestrA GRAccess COM interop. Includes session daemon, IPC protocol, and llm-json envelope contract. - grdb: SQL/DDL exploration of the Galaxy Repository database. DDL captures, reusable queries, hierarchy / contained-name <-> tag-name translation notes. - histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL linked-server, extension tables, every wwXxx time-domain extension, every retrieval mode, alarm/event SQL recipes, REST API. Distilled from the 243-page Historian Retrieval Guide. Root contains: - CLAUDE.md: thin index pointing into each tool's README. - DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
86 lines
4.9 KiB
Markdown
86 lines
4.9 KiB
Markdown
# Internationalizing Objects
|
||
|
||
If your object will be used in localized environments, you can internationalize it by defining a multilingual dictionary that contains translated strings for the target locales. At run time, the object can retrieve the appropriate strings for the locale it is used in, and show those translated strings to the end user.
|
||
|
||
## About Internationalizing Objects
|
||
|
||
By internationalizing an object, you enable it to run in various language environments and use different translated text messages, prompts, etc. in each case. For example, assume that you develop a complex object with its own custom editor pages. Customers in North America would expect to see English editor pages. On the other hand, customers in South America might use the object on a Spanish operating system and expect to see the editor pages in Spanish.
|
||
|
||
One way to do this is to create and maintain separate language versions of the object. However, this makes it very hard to maintain and update your code. A better way is to maintain one object version that will use the correct translated strings depending on the locale it is used in.
|
||
|
||
To do this, you separate the object’s code (which works identically in all locales) from the translatable text phrases (which are different for each locale). The translatable content in the code is replaced with abstract phrase IDs. The object then retrieves the appropriate translated content for whatever phrase ID it needs, when it needs it.
|
||
|
||
If an ApplicationObject contains local primitives, all local primitives use the object’s main dictionary. Reusable primitives, on the other hand, have their own dictionary.
|
||
|
||
To internationalize your objects, the ArchestrA Object Toolkit provides:
|
||
|
||
- An object dictionary that stores translated strings for each resource ID
|
||
- A function to retrieve translated strings for a resource ID
|
||
|
||
For more information, see Configuring the Object Dictionary and Retrieving Localized Dictionary Strings.
|
||
|
||
## Configuring the Object Dictionary
|
||
|
||
For each translatable resource (“phrase”), the object dictionary defines an ID and translated strings for all locales that the object will be used in. You could visualize it as a table like the following:
|
||
|
||
| Phrase ID | English | Spanish | German |
|
||
| --- | --- | --- | --- |
|
||
| idsWelcome | Welcome | Bienvenidos | Willkommen |
|
||
| idsValve1 | Valve 1 | Válvula 1 | Ventil 1 |
|
||
| ... | ... | ... | ... |
|
||
|
||
When you request the phrase “idsWelcome” on an English operating system, you get the string “Welcome.” On a Spanish operating system, you get “Bienvenidos” instead, and so on.
|
||
|
||
The object dictionary is saved as an XML file with the .aaDCT extension. By default, it contains only a sample entry, and you have to add phrases and translations before you can use it.
|
||
|
||
You can edit the dictionary using any text editor or a special XML editor. For more information, see Dictionary File Format and Structure and Editing the Dictionary in Visual Studio.
|
||
|
||
### Dictionary File Format and Structure
|
||
|
||
The XML dictionary file has the following structure:
|
||
|
||
```csharp
|
||
<Dictionary>
|
||
<Phrase_Index PhraseID="SampleEntry">
|
||
<Language LangID="1033">
|
||
<VALUE>English string</VALUE>
|
||
</Language>
|
||
<Language LangID="1031">
|
||
<VALUE>String translated into German</VALUE>
|
||
</Language>
|
||
... more <Language> elements for other languages ...
|
||
</Phrase_Index>
|
||
<Phrase_Index PhraseID="Entry2">
|
||
... <Language> elements ...
|
||
</Phrase_Index>
|
||
</Dictionary>
|
||
```
|
||
|
||
There is a single `Phrase_Index` element for every translatable string. Its `PhraseID` attribute defines the ID by which you can access the string.
|
||
|
||
Each `Phrase_Index` element contains one `Language` element for each language-specific translation of the string. The `LangID` attribute of the `Language` element specifies the locale that the translation applies to.
|
||
|
||
Each `Language` element contains a single `VALUE` element with the translated string for the specified locale.
|
||
|
||
### Editing the Dictionary in Visual Studio
|
||
|
||
You can directly edit the object dictionary using the built-in Visual Studio editor.
|
||
|
||
**To edit the dictionary in Visual Studio**
|
||
|
||
1. In the Object Design View, double-click **Dictionary**. Visual Studio opens a tab with the dictionary file.
|
||
|
||
You can now add or edit strings according to the dictionary XML structure (see Dictionary File Format and Structure).
|
||
|
||
## Retrieving Localized Dictionary Strings
|
||
|
||
To retrieve a localized dictionary string at config time or run time, simply use the GetText method. For example:
|
||
|
||
```csharp
|
||
GetText("idsError");
|
||
```
|
||
|
||
This statement gets the translation for the dictionary entry with the ID “idsError” for the default locale of the process it is called from. For config time code, this is the default locale of the Galaxy,that is, the OS locale at the time the Galaxy was created.
|
||
|
||
For more information, see the documentation on the GetText method in the *ArchestrA Object Toolkit Reference Guide*.
|