path: root/plugins/doc/org.eclipse.papyrus.infra.internationalization.doc/src/site/mediawiki/internationalizationDev.mediawiki

= Internationalization =
The internationalization is the way to manage your model with a specific language by labels. Like Eclipse, the internationalization is managed by the 'properties' file which are defined depending language as following (with for example, english language in US country):
* ''modelName'''''_en_US.properties'''
* ''modelName'''''_en.properties'''
* ''modelName'''''.properties'''

[[Image:images/PropertiesModelExplorer.png|frame|none|Properties files in Model Explorer]]

== Plugins ==
The plugins for the internationalization are the following:
* <code>org.eclipse.papyrus.infra.internationalization</code>: it contains:
** Internationalization Meta-model
** Generated code from the Meta-model
** The model resources for the internationalization entries (key and label of internationalized objects) and internationalization preferences
** Utils classes to manage the labels and the preferences
* <code>org.eclipse.papyrus.infra.internationalization.edit</code>: contains generated edit code from the Meta-model
* <code>org.eclipse.papyrus.infra.internationalization.common</code>: contains all the common classes to manage command modification and some utils for the internationalization preferences. It contains the <code>IInternationalizationEditor</code> interface too which allows to define the editor that can be internationalized.
* <code>org.eclipse.papyrus.infra.internationalization.controlmode</code>: contains the needed elements to manage the control mode for the properties and the preferences files
* <code>org.eclipse.papyrus.infra.internationalization.ui</code>: contains the needed ui classes especially for the internationalization preferences
* <code>org.eclipse.papyrus.infra.internationalization.utils</code>: contains all the needed utils classes to manage the label which can be used to get the diagrams and tables labels
* <code>org.eclipse.papyrus.infra.editor.welcome.internationalization</code>: contains the needed classes to manage the preferences in the welcome page
* <code>org.eclipse.papyrus.uml.internationalization</code>: contains the UML internationalization model resource which can manage the UML elements in the properties file
* <code>org.eclipse.papyrus.uml.internationalization.edit</code>: contains the <code>InternationalizationUMLItemProviderAdapterFactory</code> which define the ItemProvider of UML elements to use the Papyrus getLabel function instead of UML getLabel function
* <code>org.eclipse.papyrus.uml.internationalization.utils</code>: contains all the needed utils classes to manage the label which can be used to get the named elements labels

== How to use internationalization ==
Instead of name, the label of objects must be displayed in Papyrus.

=== How the labels are managed in properties file ===
Each element which have a label must be written in the properties file as following:
* If this is a diagram: 
** '''_labelDiagram_'''''DiagramOwnerQualifiedName'''''_label_'''''DiagramName'' '''=''' ''DiagramLabel''
* If this is a table: 
** '''_labelTable_'''''TableOwnerQualifiedName'''''_label_'''''TableName'' '''=''' ''TableLabel''
* If this is an UML NamedElement: 
** '''_label_'''''NamedElementQualifiedName'' '''=''' ''NamedElementLabel''

[[Image:images/LabelsInternationalizationExample.png|frame|none|Example of internationalization labels]]

=== Infra (Diagrams and Tables) ===
For the Diagrams and the Tables, UML is not needed. So to use the internationalization, you just need to:
* add the org.eclipse.papyrus.infra.internationalization.utils dependency
* use methods/functions of <code>LabelInternationalization</code>

The <code>LabelInternationalization</code> class contains the following needed methods/functions:
{| class="wikitable" border="1"
! style="text-align: center;" | Method/Function
! style="text-align: center;" | Parameters
! style="text-align: center;" | Description
|-
! style="font-weight: bold;" | getInstance
| 
| The the instance of LabelInternationalization
|-
! style="font-weight: bold;" | getDiagramLabelWithoutName
| Diagram
| Get the label of the diagram without getting its name if label is not available
|-
! style="font-weight: bold;" | getDiagramLabel
| Diagram
| Get the label of the diagram or the name if the diagram label is not available
|-
! style="font-weight: bold;" | setDiagramLabel
| Diagram, String, Locale
| Set the label (in parameter) of the Diagram for the locale needed (if <code>null</code>, the current must be used) without using command
|-
! style="font-weight: bold;" | getSetDiagramLabelCommand
| EditingDomain, Diagram, String, Locale
| Get the command to set the label (in parameter) of the Diagram for the locale needed (if <code>null</code>, the current must be used)
|-
! style="font-weight: bold;" | getTableLabelWithoutName
| Table
| Get the label of the Table without getting its name if label is not available
|-
! style="font-weight: bold;" | getTableLabel
| Table
| Get the label of the Table or the name if the Table label is not available
|-
! style="font-weight: bold;" | setDiagramLabel
| Table, String, Locale
| Set the label (in prameter) of the Table for the locale needed (if <code>null</code>, the current must be used) without using command
|-
! style="font-weight: bold;" | getSetTableLabelCommand
| EditingDomain, Table, String, Locale
| Get the command to set the label (in parameter) of the Table for the locale needed (if <code>null</code>, the current must be used)
|}

=== UML Named Elements ===
For the UML NamedElement, to use the internationalization, you just need to:
* add the org.eclipse.papyrus.uml.internationalization.utils dependency
* use the <code>UMLLabelInternationalization</code>

The <code>UMLLabelInternationalization</code> class contains following needed methods/functions:
{| class="wikitable" border="1"
! style="text-align: center;" | Method/Function
! style="text-align: center;" | Parameters
! style="text-align: center;" | Description
|-
! style="font-weight: bold;" | getInstance
| 
| The the instance of LabelInternationalization
|-
! style="font-weight: bold;" | getLabelWithoutName
| NamedElement
| Get the label of the NamedElement without getting its name if label is not available
|-
! style="font-weight: bold;" | getLabel
| NamedElement
| Get the label of the NamedElement or the name if the NamedElement label is not available
|-
! style="font-weight: bold;" | setLabel
| NamedElement, String, Locale
| Set the label (in parameter) of the NamedElement for the locale needed (if <code>null</code>, the current must be used) without using command
|-
! style="font-weight: bold;" | getSetLabelCommand
| EditingDomain, NamedElement, String, Locale
| Get the command to set the label (in parameter) of the NamedElement for the locale needed (if <code>null</code>, the current must be used)
|-
! style="font-weight: bold;" | getKeywordWithoutName
| Stereotype
| Get the keyword of the Stereotype without getting its name if keyword is not available
|-
! style="font-weight: bold;" | getKeyword
| Stereotype
| Get the keyword of the Stereotype or the name if the Stereotype keyword is not available
|-
! style="font-weight: bold;" | setKeyword
| Stereotype, String, Locale
| Set the keyword (in parameter) of the Stereotype for the locale needed (if <code>null</code>, the current must be used) without using command
|-
! style="font-weight: bold;" | getSetKeywordCommand
| EditingDomain, Stereotype, String, Locale
| Get the command to set the keyword (in parameter) of the Stereotype for the locale needed (if <code>null</code>, the current must be used)
|}

== Internationalization preferences ==
Two preferences are managed in the Papyrus model:
* useInternationalization: Boolean to determinate if the internationalization must be used
* language: String to define the selected language for the internationalization


The preferences are stored as EAnnotation:
* in the notation file in this is a private storage
* in the metadata in this is not a private storage


[[Image:images/InternationalizationPreferences.png|frame|none|Internationalization preferences management]]


Those preferences are managed in a <code>PreferenceStore</code> in the activator of org.eclipse.papyrus.infra.internationalization.common plugin.

The <code>PapyrusProjectScope</code> allows to manage the preferences for the Eclipse project with Papyrus model name.

== Control mode ==
The sub-models are managed with the properties files.
Indeed, when an object is created as sub-model, the key representing this object or its descendance in the properties files must be moved in sub-properties files corresponding to the controlled object.
During this sub-model creation, the qualified names of the keys that are moved change, the new qualified names are calculated from the root of the sub-model.

=== What is it managed ===
The managed files/objects are:
* The properties files and their keys
* The notation and the internationalization preferences if this is private storage

=== How is it managed ===
The <code>org.eclipse.papyrus.infra.internationalization.controlmode</code> manage all the control mode for the internationalization.

The properties files are managed by:
* <code>PropertiesControlParticipant</code> and <code>PropertiesUncontrolParticipant</code> for the participants
* <code>CreatePropertiesControlResourceCommand</code> which define the command to create the controlled properties file
* <code>RemovePropertiesControlResourceCommand</code> which define the command to delete the controlled properties file
* <code>ControlPropertiesCommand</code> which define the command to manage the internationalization entries to move into the controlled properties

The notation and the internationalization preference storage are managed by:
* <code>InternationalizationAnnotationControlParticipant</code> for the participant (uncontrolled is not needed because the parent is priority)
* <code>InternationalizationAnnotationCommand</code> which define the command to create the internationalization preference into the controlled notation file

== Specificities ==
=== Loading properties resources ===
The properties resources are loaded and managed by the <code>UMLInternationalizationModelResource</code> class.
This <code>UMLInternationalizationModelResource</code> class inherit from <code>InternationalizationModelResource</code> from infra plugins.
The load is managed as 2 steps:
# Load the file and read the content to create the <code>InternationalizationLibrary</code> with diagrams and tables labels reconciliation with existing diagrams and tables.
# Loop on content to resolve the UML dependencies in properties files to reference the existing UML objects.

So, after the load, the resolveable properties are managed as UML object, diagram or table as key of <code>InternationalizationLibrary</code>

=== InternationalizationUMLItemProviderAdapterFactory ===
The <code>InternationalizationUMLItemProviderAdapterFactory</code> extends <code>UMLItemProviderAdapterFactory</code> and allows to redefine the ItemProvider of UML elements to get the Papyrus internationalization getLabel instead of UML getLabel.

If an ItemProvider of UML element needs to be redefined, the ItemProviderAdapterFactory must ihnerit from this class instead of <code>UMLItemProviderAdapterFactory</code>.

=== Diagram and Table owner QualifiedName ===
The diagrams and the tables are managed in the infra plugins, however, the owner of the diagram or table must be serialized in the properties file by its QualifiedName. So the owner QualifiedName is managed by the class <code>QualifiedNameUtils</code> and calculated manually.

=== Editors ===
The diagrams and tables are managed by the internationalization. To do this, the diagram and table editor must inherit from <code>IInternationalizationEditor</code> which allows to modify part name and refresh the editor with the label.
If any new editor is comming with internationalization management, this one must ihnerit from <code>IInternationalizationEditor</code> too.