How to help us render IEC-CIM in your (native) language

Ontologies are fantastic ways to standardize data definitions. They help us structure the knowledge we have in to a format that can be verified (through peer review or inferencing) and be reused. However most people do not speak english as their first (or even second) language and sharing knowledge happens mostly through language. Especially at utilities, which are often regional organizations, where domain experts do not always master the English language enough to understand a model like the IEC-CIM, it is important to make this knowledge model available to them in a language that they understand. So one of the features of linked data that we really want to get maximum use of is that of language localization in the annotations.

However, the puffins at Puffin Semantics speak only English and Dutch well enough to be able to do this work in the domains we are familiar with. So any help is much appreciated.

Help us translate the IEC-CIM in your language!

If you speak any language other than English, or already have a translation of the IEC-CIM that you use in your organization, please help us out! You do not need to translate all of the CIM, even the translation of a couple of classes, attributes or associations would help.

Creating a translation

If you are ready to help us create more CIM translations: Fantastic. A couple of things to know:

• it does not matter which version of CIM you use. For both the methods we describe the right translation should still end up with the right object
• if we are lucky and many people contribute to this, we might get disagreements about how a certain term should be translated.
  • should this happen: make an “issue”.
  • we cannot decide over which translation is best (especially for languages we don’t speak), so please sort this out amongst each other.
  • be mindful of organization specific terminology and try to avoid proposing those as translation.
  • this should go without saying: people volunteer their time for this so appreciate that and be respectful in your discussions.

In this instruction, we give 2 methods for supplying you with your translation. Via Protege and via Sparx EA. Either method should work.

The Github project

In order to bring the work on translations together, we have created a github repository. A couple of things to know about this repo:

• it is licensed under the Apache 2 open source license. we are not lawyers, but in our superficial understanding of the domain and how organizations cooperate within it, this license make sense.
• The IEC-CIM community is also moving towards git. If at all possible we intend to transfer ownership of this repository as soon as possible

In the repo you will see different files for different language. If your language is already there, please add your work to these files.

Option1: RDF file using Protégé

• pro’s
  • you can provide translations for both the labels of the objects as well as their textual definition
  • you do not need a Sparx EA license
  • works better with git
• cons
  • you need to learn to use Protégé (if you don’t know it already)

Step 1: download and install Protégé

Protégé is an open source ontology editor created by Stanford. There is a web-based verion and a desktop version. For this instruction, we use the desktop application.

Download Protégé here (scroll down).

Find documentation here.

step 2 create a file and import the IEC-CIM ontology

To make this step easier, we have prepared an example file that you can use as a template. When you open this file in Protégé you should see this (after importing is done):

If the import of the ontology cannot be resolved, enter this URL: https://raw.githubusercontent.com/PuffinSemantics/IEC-CIM-Ontology/main/TheCimOntology.owl

Navigate to the Entities tab and start translating the concepts that you know the translation of.

Click on the + button in the annotations pane.

If you want to translate the label make sure you select the label and set the correct language. (either select it from the drop down or type the language abbreviation)

If you want to translate a definition, make sure you select the comment and again set the correct language.

Save (ctrl+s) your work when you are done. To check your work, open the text file in a text editor. It should look something like this:

Add the file to your local copy of the git repository and make a “pull request”.

A final word on RDF files: yes, they are text files so strictly speaking you could just open a text editor and ‘translate away’. However, unless you feel very confident about the rdf/xml syntax, we would advise against doing so.

Option2: .eap file using Sparx Enterprise Architect

• pro’s
  • You can do this in tooling you are probably already familiar with
• cons
  • you need to have an Sparx EA license
  • you can only tranlsate labels, textual definitions are at this moment not possible

This option should be more familiar to most of those familiar with CIM. Open any Diagram that contain classes you wish to translate:

In this case, we translate “Switch” to Dutch: Schakelaar. If you wish to render the diagram in your local language, right click on the diagram, select “properties”. On the Diagram tab, select “Use Aliase if Available”

The diagram should now show the translation you have made.

Sparx Enterprise Architect only allows one alias per object. So each model can only contain one language localization unfortunately. In order to have your language be part of the project, save the file as iec-cim-yourlanguage.eap (example: iec-cim-nl.eap) in your clone of the git repository and make a pull request.

Be Ware if you are working in your organizations EA model, be ware of any extensions your organization has made and whether they can be made public! Once published to our repository that content falls under the Apache 2 license!

Conclusion

If you have gotten this far: you are awesome! If you have any questions send us a message.

• language localization
• ontology viewer