Preferences Language

Introduction

Petro-SIM now offers increased translation and native language character support. This means that many views and messages in Petro-SIM can now be shown in a language other than English. Translation is supported starting with version 3.3.

How does it work?

Petro-SIM maintains a translation file. When something is about to be displayed, it is quickly translated using the contents previously read from this file. New translations can be added to the file as they are encountered (needed). A translation for everything is not required, which means the file can be kept small and manageable and focused on specific views. The file can also be easily edited using a text editor.

The same translation files can be used with multiple versions of Petro-SIM. Note that individual words are not necessarily translated, but rather phrases and strings as they are encountered. The translations are also shared between different views.

When translation is activated, the translation file is loaded and maintained in memory. When translation is turned off again, the file is saved out if any new translations have been added.

What about native language characters?

In addition to standard ANSI characters such as ABC, Unicode allows a much larger range characters to be displayed, such as Chinese language characters. The Petro-SIM translation feature supports Unicode. The translation file can be either a standard ANSI text file, or UTF-16 (little-endian) Unicode text file.

How do I use this feature in Petro-SIM?

In Petro-SIM 4.0 and earlier, go to the Preferences view, Resources, Language page.

In Petro-SIM 4.1 and later, go to the Preferences view, Display, Language page.

From the locale drop down, choose the desired language. The list of languages is determined by the presence of any translation files in the Petro-SIM support directory or in the all user application data directory (C:\Documents and Settings\All Users\Application Data or C:\ProgramData, depending on your Windows version).

Then check Activate Translation Feature. This will load the translation file (if one exists) from disk and start translating views. Translation will stop when this option is unchecked. When this option is unchecked, the translation file will be saved out if any new translations have been added or changed.

When translation is turned on, Petro-SIM will check to see if the shared user application data directory contains a matching translation file. If not, and there is one in the Petro-SIM support directory, it will be copied to a local directory shared by all the computer users. (Typically this is C:\Documents and Settings\All Users\Application Data, though the exact location depends on your Windows version. On Windows 7 the location may be C:\ProgramData.) This copy of the file will be writable and can be manually edited. If a new standard translation file is released with a Petro-SIM update, Petro-SIM will ask you about using the newer version.

While the translation feature is active, click Edit Translations... to open up a translation editor view. This view shows all translations, recent translation, or translations that contain a given search string. You can temporarily lock translations to edit them in this view.

Click on Editor... to select an external text editor. Click Edit... to use the external editor to edit the translation file. Petro-SIM will save the translation file to disk if need be, stop the translation (to avoid possible conflicts), and open the selected editor, pointing it at the translation file. After editing and saving the translation file, click "Activate" to reload and re-enable translation again.

You can enter a Translation File Directory if you wish to use a directory other than the default directory for the translation file. This can be used if you wish to share one translation file with other issues. You should pick a directory where you have write access (note that under Windows Vista and 7, users do not have write access to root directories or certain directories such as Program Files), if you wish to edit any translations. If need be, the location can be a slow network location, as the translation file is not constantly accessed.

What about the Windows Language Bar?

This bar (configurable via the Control Panel, Regional and Language Settings) can be used to change the Petro-SIM language, if Petro-SIM has focus at the time the change is made. You can also use left Alt-Shift to effect a change via the language bar functionality. Note that this change will not work if a Petro-SIM web browser (such as the Welcome screen) has focus. You can work around this by opening the preferences view from the button bar. The language bar is also handy to switch back to English if you switched to a foreign language which you do not understand and can not get back to the Language Preferences page. Alternatively, translation can be easily switched on or off in Petro-SIM by pressing Ctrl-Shift-L.

I switched Petro-SIM to language X and opened the language bar but it shows EN?

With Petro-SIM selected, the language bar can be used to change the Petro-SIM translation language. If the language is changed within Petro-SIM, the bar will not detect the change. But it can still be used to effect a translation language change in Petro-SIM.

How do I edit translations inside Petro-SIM, using the editor?

First of all, turn on translations by clicking on Activate Translation Feature. Then click on Edit Translations... to open up a translation editor view:

The view has three options: Show All Translations - This shows all the translations. The translations are sorted by string length, and then alphabetically. Show Recent Translations - Translation is performed on the fly while views update (repaint). This page will show recent translations. The view contents will change if you flip a page on another view for example. So if you see something in a view which is not getting translated properly, you can use this option to find it quickly. Filter - This option allows you to search for strings in the translation table. All strings that contain the given substring will be shown.

Note that by default you can not edit a translation in the view unless you check Lock for edit. This is because the translation table is dynamics and changes as views paint or gets edited. So to change a value, lock the translations, enter a translation, and unlock it again. Next the view repaint, the new translation will get used. You can trigger a repaint of Petro-SIM by closing and opening the view, or simply minimizing Petro-SIM or a view inside it.

Can I use any editor to edit the translation file?

Yes, but the editor must support the following:

• Be able to load and save the translation file in ANSI or Unicode UTF-16 text format. Petro-SIM will mark the file appropriately.
• Be able to support files larger than 64 K.
• Be able to display Unicode characters.

You can use Notepad or one of numerous free alternatives such as Notepad++. Do note that some older versions of Notepad are limited to files less than 64 K in size (though if you are using Windows XP or later it should probably be fine).

The translation files must be in plain ANSI format, or in Unicode UTF-16 format (marked with standard BOMs). Use ANSI format for languages that use Latin characters, and UTF-16 for languages that use special characters. You can load the file and save it out in the desired format if you need to change the format. Note that using ANSI where possible will reduce memory use slightly.

Can I edit the translation file myself?

Yes, the full name of the translation file is shown in the Preferences view, Resources, Language page. Be sure to turn off translation in Petro-SIM before editing the file (Ctrl-Shift-L), to prevent your edits possibly getting overwritten. Edit the file manually, and then turn translation on in Petro-SIM to have the changes take effect. When translation is turned off in Petro-SIM, it might save the translation file if translations have been changed. When translation is turned on, the file is loaded back into memory again. You do not need to restart Petro-SIM for new translations to take effect.

Notepad is not displaying characters correctly when I edit the translation file. I see blocks or question marks.

There are two ways to fix this:

• Make sure your version of Windows is set to support the language in question. Go to the Control Panel and look at the Regional and Language settings. You can add extra languages support, and configure code page support so that Unicode characters for said language will be displayed properly.
• Change the font Notepad uses. Click Format, Font, and choose a Unicode capable font. If Arial Unicode MS is available on your system (it installs with MS Office), then it is a good choice. This option can be used to display Unicode characters if you do not wish to install support for a specific language.

When I turn on translation, I most see blocks or vertical stripes or questions marks in Petro-SIM, and not the right characters.

• Make sure your version of Windows is set to support the language in question. Go to the Control Panel and look at the Regional and Language settings. You can add extra languages support, and configure code page support so that Unicode characters for said language will be displayed properly. Since this setting will impact font generation, restart Petro-SIM if need be.
• In the Preferences view, Language page of Petro-SIM, check the Use Unicode Font option. You should not have to check this option if Windows is properly configured to support the chosen language and map the code pages accordingly.

When using translation, some of the buttons and other display widgets are not wide enough to show all the text.

Most languages require more room for translations than English. The simplest solution is to edit the translation file and provide shorter translations where need be. You can also edit the views (ask support how to do this) and move items around to make more room. Please let us know for which views you do this so that we can rearrange them. Note that is if the translations are too long and do not fit on the screen, that you can hover the mouse over the view to see the full string.

I want to change some of the translations

Click Edit Translations.... This brings up a view that lets you see all translations, recent translations, as well as search for translations. You can enter new translations directly into this view. New entries will be used as soon needed to repaint a view somewhere.

The fastest view to edit translations is to simply edit the translation text file manually. Edit the translation file using an external text editor. Periodically save it. After each save, press Ctrl-Shift-L in Petro-SIM to turn translation off and then press the keystrokes again to turn it back again. This wil cause the translation file to be reloaded. Petro-SIM does not need to be restarted.

Be sure to make frequent timed backups of the file in case it accidentally gets damaged or overwritten.

Why do I need to sometimes lock translations in Petro-SIM before editing?

This is to avoid the translations list being changed (due to something painting) while you are editing it.

What are the %s and %d strings in some translations?

These format strings get replaced by other strings (such as the name of a unit or unit operations) or numbers. When you translate a string, be sure that the translated string contains the same number of format strings, otherwise the translated string might not end up being used.

When editing the translation file, where do I find the English strings to translate?

• Read the comment at the top of the translation file. Strings which are untranslated, appear in English and are marked as :ttran. A section which is already translated is marked as :tran. Do not translate text which appears underneath :key or underneath :en. Rather translate text that appears underneath :tran (if need be) or underneath :ttran. You can optionally change :ttran to :tran to mark text as having been translated already.
• The :key section will usually contain the untranslated text (all lower case).
• Where the key is not the original string to be translated, the original English string it is written under :en. Note that the actual string here is ignored when the translation file is read by Petro-SIM.

The translation key may also be a key from the Petro-SIM.sdb of iface.sdb files (such as NameNotUnique) found in the Petro-SIM installation support directory. These two SDB files are text files and can be viewed using Notepad. These keys are usually used in error messages, response messages and some trace messages.

Additionally, some refinery reactors or refinery assay code generates error and trace messages based on another key. The key could be something like "sol 188". The "sol" refers to a .msgc key file where the message can be found and the number refers to the message number. These messages can have arguments marked as @1, @2 and such. If the argument needs to be translated as well, then it can be marked as @T1 for example. The .msgc files are available from KBC on request.

I love the translation feature, but some things are not translated. I would like to have them translated.

First of all, make sure that:

• You have checked "Activate Translation Feature" on the Preferences view, Resources, Language page.
• On the Edit Translations page, make sure the translations are not locked for editing.
• Look at the translation file to make sure it does not have the English string as a translation, or that the translation appears twice with one untranslated (though Petro-SIM will warn you about this when loading a translation file).
• You can also search the .SDB files described earlier for the string and use the key in the SDB file as the key in the translation file.

If the string can not be translated, please email a screen shot (and your translation file) to the KBC software helpdesk (note that you can easily email a screen shot via the File menu in Petro-SIM).

What impact will translation have on Petro-SIM?

• Some views may require slightly longer to repaint (refresh) due to the translation and more complex characters. However, this impact should be totally negligible and not be noticeable.
• Petro-SIM will use more memory to keep the translation file in memory. How much depends on the size of your translation file. Generally translations will consume a couple of megabytes of memory. However, this is unlikely to be a concern.
• Note that the translation settings are saved in the preferences file. If Petro-SIM is run invisibly or in the back ground, you likely want to deactivate any translation so as to maximize speed.

I would like to share my translation file with others.

• If you have a nice translation file, you simply email it to other users (who can save it over their translation file (look in the preferences view to see where it is, it will typically be (C:\Documents and Settings\All Users\Application Data)). Since the translation file is a text file, free utilities such as WinMerge can be used to compare and merge files.
• Translation files may be installed with Petro-SIM (in the support directory) and copied to the user location when translation is first used, if no user translation is present. So you can submit your translation file to the KBC helpdesk for inclusion in the next version.

I have switched Petro-SIM to language XX. But I do not understand language XX. How do I turn off translations again?

You can change the translation in three ways:

• In Petro-SIM press Ctrl-Shift-L to toggle translation on and off.
• Use the Windows language bar with Petro-SIM selected to change the language. Changing it to another language and then back to english will turn off translation.
• Exit Petro-SIM, delete your preference file (open Windows explorer and go to %APPDATA%\KBC), and start Petro-SIM again.

I want to add my own translation. Do I have to manually add them or can Petro-SIM add them for me so I can just check and verify them?

There are options in the preferences view to add translation tot he file automatically. So if something is not in there but needed, Petro-SIM will add it. You can then use a tool such as WinMerge to compare the old and new files and fix up the translations. To get at the extra options, you need to add a registry entry on your machine, as follows:

Click start run, and enter "regedit". The registry editor will open up. Expand the tree HKEY_CURRENT_USER, and under it expand Software, and under that KBC Profimatics. Right mouse click on KBC Profimatics and choose New, key. It will add a new key and let you type a name for it. Set its name to PetroSIMTranslation. Now restart Petro-SIM and you should see additional options in the preferences view.

I love this feature, how can I provide feedback to improve it?

You can send an email to: software at kbcat.com