packages.tex

\chapter{Packages}\label{packages}

Packages in Modelica may contain definitions of constants and classes including all kinds of specialized classes, functions, and subpackages.
By the term subpackage we mean that the package is declared inside another package, no inheritance relationship is implied.
Parameters and variables cannot be declared in a package.
The definitions in a package should typically be related in some way, which is the main reason they are placed in a particular package.
Packages are useful for a number of reasons:
\begin{itemize}
\item
  Definitions that are related to some particular topic are typically grouped into a package.
  This makes those definitions easier to find and the code more understandable.
\item
  Packages provide encapsulation and coarse-grained structuring that reduces the complexity of large systems.
  An important example is the use of packages for construction of (hierarchical) class libraries.
\item
  Name conflicts between definitions in different packages are eliminated since the package name is implicitly prefixed to names of definitions declared in a package.
\item
  Information hiding and encapsulation can be supported to some extent by declaring \lstinline!protected! classes, types, and other definitions that are available only inside the package and therefore inaccessible to outside code.
\item
  Modelica defines a method for locating a package by providing a standard mapping of package names to storage places, typically file or directory locations in the file system.
\end{itemize}


\section{Package as Specialized Class}\label{package-as-specialized-class}

The package concept is a specialized class (\cref{specialized-classes}), using the keyword \lstinline!package!.


\section{Importing Definitions from a Package}\label{importing-definitions-from-a-package}

The \lstinline!import!-clause makes public classes and other public definitions declared in some package available for use by shorter names in a class or a package.
It is the only way of referring to definitions declared in some other package for use inside an encapsulated package or class.

\begin{nonnormative}
The \lstinline!import!-clauses in a package or class fill the following two needs:
\begin{itemize}
\item
  Making definitions from other packages available for use (by shorter names) in a package or class.
\item
  Explicit declaration of usage dependences on other packages.
\end{itemize}
\end{nonnormative}

%TODO-FORMAT Should be formatted using tabs or tabular?
An \lstinline!import!-clause\indexinline{import} can occur in one of the following syntactic forms:

% Note a syntactic form cannot be written as a single \lstinline due to LaTeXML problem reported here:
%   https://github.com/brucemiller/LaTeXML/issues/1274 (marked as fixed as of commit 80d7940)
% Instead, we need to break up the \lstinline in mysterious ways.  Be sure to check that the generated HTML
% looks OK when making changes!

\lstinline!import $\mathit{definitionname}$;! (qualified import of top-level definition)

\lstinline!import $\mathit{packagename}$.!% Break up \lstinline as workaround for LaTeXML issue described above.
\lstinline!$\mathit{definitionname}$;! (qualified import)

\lstinline!import $\mathit{packagename}$.{$\mathit{def}_{1}$, $\mathit{def}_{2}$, $\ldots$, $\mathit{def}_{n}$};! (multiple definition import)

\lstinline!import $\mathit{packagename}$.*;! (unqualified import)

\lstinline!import $\mathit{shortname}$ = $\mathit{definitionname}$;! (renaming import of top-level definition)

\lstinline!import $\mathit{shortname}$ = $\mathit{packagename}$.!% Break up \lstinline as workaround for LaTeXML issue described above.
\lstinline!$\mathit{definitionname}$;! (renaming import)

Here $\mathit{packagename}$ is the fully qualified name of the imported package including possible dot notation and $\mathit{definitionname}$ is the name of an element in a package.
The multiple definition import is equivalent to multiple single definition imports with corresponding $\mathit{packagename}$ and definition names.


\subsection{Lookup of Imported Names}\label{lookup-of-imported-names}

This section only defines how the imported name is looked up in the \lstinline!import!-clause.
For lookup in general -- including how \lstinline!import!-clauses are used -- see \cref{static-name-lookup}.

Lookup of the name of an imported package or class deviates from the normal lexical lookup.
For example, consider \lstinline!A.B.C! in the \lstinline!import!-clauses \lstinline!import A.B.C;!, \lstinline!import D = A.B.C;!, or \lstinline!import A.B.C.*;!.
Here, lookup starts with the lexical lookup of the first part of the name (\lstinline!A!) at the top level.

Qualified \lstinline!import!-clauses may only refer to packages or elements of packages, i.e., in \lstinline!import A.B.C;! or \lstinline!import D = A.B.C;!, \lstinline!A.B! must be a package.
Unqualified \lstinline!import!-clauses may only import from packages, i.e., in \lstinline!import A.B.*;!, \lstinline!A.B! must be a package.

\begin{nonnormative}
In \lstinline!import A;! the class \lstinline!A! can be any class which is an element of the unnamed top-level package.
\end{nonnormative}

\begin{nonnormative}
For example, if the package \lstinline!ComplexNumbers! would have been declared as a subpackage inside the package \lstinline!Modelica.Math!, its fully qualified name would be \lstinline!Modelica.Math.ComplexNumbers!.
$\mathit{definitionname}$ is the simple name without dot notation of a single definition that is imported.
A $\mathit{shortname}$ is a simple name without dot notation that can be used to refer to the package after import instead of the presumably much longer $\mathit{packagename}$.

The forms of \lstinline!import! are exemplified below assuming that we want to access the addition operation of the hypothetical package \lstinline!Modelica.Math.ComplexNumbers!:
\begin{lstlisting}[language=modelica]
import Modelica.Math.ComplexNumbers;       // Accessed by ComplexNumbers.Add
import Modelica.Math.ComplexNumbers.Add;   // Accessed by Add
import Modelica.Math.ComplexNumbers.{Add,Sub}; // Accessed by Add and Sub
import Modelica.Math.ComplexNumbers.*;     // Accessed by Add
import Co = Modelica.Math.ComplexNumbers;  // Accessed by Co.Add
\end{lstlisting}
\end{nonnormative}


\subsection{Rules for Import-Clauses}\label{summary-of-rules-for-import-clauses}\label{rules-for-import-clauses}

The following rules apply to \lstinline!import!-clauses:
\begin{itemize}
\item
  The \lstinline!import!-clauses are \emph{not} inherited.
\item
  The \lstinline!import!-clauses are not named elements of a class or package.
  This means that \lstinline!import!-clauses cannot be changed by modifiers or redeclarations.
\item
  The \emph{order} of \lstinline!import!-clauses does not matter.
\item
  One can only import \emph{from} packages, not from other kinds of classes.
  Both packages and classes can be imported \emph{into}, i.e., they may contain \lstinline!import!-clauses.
\item
  An imported package or definition should always be referred to by its fully qualified name in the \lstinline!import!-clause.
\item
  Multiple qualified \lstinline!import!-clauses shall not have the same import name (see \cref{simple-name-lookup}).
\end{itemize}


\section{The Modelica Library Path -- MODELICAPATH}\label{the-modelica-library-path-modelicapath}

The top-level scope implicitly contains a number of classes stored externally.
If a top-level name is not found at global scope, a Modelica translator shall look up additional classes in an ordered list of library roots, called \lstinline!MODELICAPATH!\indexinline{MODELICAPATH}.

\begin{nonnormative}
The implementation of \lstinline!MODELICAPATH! is tool dependent.
In order that a user can work in parallel with different Modelica tools, it is advisable to not have this list as environment variable, but as a setting in the respective tool.
Since \lstinline!MODELICAPATH! is tool dependent, it is not specified in which way the list of library roots is stored.
Typically, on a Windows system \lstinline!MODELICAPATH! is a string with path names separated by `\filename{;}' whereas on a Linux system it is a string with path names separated by a `\filename{:}'.
\end{nonnormative}

In addition a tool may define an internal list of libraries, since it is in general not advisable for a program installation to modify global environment variables.
The version information for a library (as defined in \cref{annotations-for-version-handling}) may also be used during this search to search for a specific version of the library (e.g., if Modelica library version 2.2 is needed and the first directory in \lstinline!MODELICAPATH! contain Modelica library version 2.1, whereas the second directory contains Modelica version 2.2, then Modelica library version 2.2 is loaded from the second directory.).

\begin{nonnormative}
The first part of the path \lstinline!A.B.C! (i.e., \lstinline!A!) is located by searching the ordered list of roots in \lstinline!MODELICAPATH!.
If no root contains \lstinline!A! the lookup fails.
If \lstinline!A! has been found in one of the roots, the rest of the path is located in \lstinline!A!; if that fails, the entire lookup
fails without searching for \lstinline!A! in any of the remaining roots in \lstinline!MODELICAPATH!.
\end{nonnormative}

If during lookup a top-level name is not found in the unnamed top-level scope, the search continues in the package hierarchies stored in these directories.

\begin{example}
\Cref{fig:roots} below shows an example \lstinline!MODELICAPATH! = \filename{"C:\textbackslash{}library;C:\textbackslash{}lib1;C:\textbackslash{}lib2"}, with three directories containing the roots of the package hierarchies \lstinline!Modelica!, \lstinline!MyLib!, and \lstinline!ComplexNumbers!.
The first two are represented as the subdirectories \filename{C:\textbackslash{}library\textbackslash{}Modelica} and \filename{C:\textbackslash{}lib1\textbackslash{}MyLib}, whereas the third is stored as the file \filename{C:\textbackslash{}lib2\textbackslash{}ComplexNumbers.mo}.

\begin{figure}[H]
  \begin{center}
    \includegraphics{modelicapath}
  \end{center}
  \caption{Roots of package hierarchies, e.g., \lstinline!Modelica!, \lstinline!MyLib!, and \lstinline!ComplexNumbers! in
  \lstinline!MODELICAPATH! = \filename{"C:\textbackslash{}library;C:\textbackslash{}lib1;C:\textbackslash{}lib2"}.}
  \label{fig:roots}
\end{figure}

Assume that we want to access the package \lstinline!MyLib.Pack2! in \cref{fig:roots} above, e.g., through an \lstinline!import!-clause \lstinline!import MyLib.Pack2;!.
During lookup we first try to find a package \lstinline!MyLib! corresponding to the first part of the name in the import-statement.
It is not found in the top-level scope since it has not previously been loaded into the environment.

Since the name was not found in the top-level scope the search continues in the directories in the \lstinline!MODELICAPATH! in the specified order.
For the search to succeed, there must be a subdirectory \filename{MyLib} or a file \filename{MyLib.mo} in one of the directories mentioned in the \lstinline!MODELICAPATH!.
If there is no such subdirectory or file, the lookup fails.
If \filename{MyLib} is found in one of the directories, the rest of the name, in this case \lstinline!Pack2!, is located in \filename{MyLib}.
If that fails, the entire lookup fails without continuing the search in possibly remaining directories.

In this example the name matches the subdirectory named \filename{MyLib} in the second directory \filename{C:\textbackslash{}lib1} mentioned in the \lstinline!MODELICAPATH!.
This subdirectory must have a file \filename{package.mo} containing a definition of the package \lstinline!MyLib!, according to the Modelica rules on how to map a package hierarchy to the file system.
The subpackage \lstinline!Pack2! is stored in its own subdirectory or file in the subdirectory \filename{MyLib}.
In this case the search succeeds and the package \lstinline!MyLib.Pack2! is loaded into the environment.
\end{example}


\section{File System Mapping of Package/Class}\label{mapping-package-class-structures-to-a-hierarchical-file-system}\label{file-system-mapping-of-package-class}

A package/class hierarchy may be represented in the hierarchical structure of the operating system (the file system).
For classes with version information see also \cref{mapping-of-versions-to-file-system}.
The nature of such an external entity falls into one of the following two groups:
\begin{itemize}
\item
  Directory in the file system.
\end{itemize}

\begin{itemize}
\item
  File in the file system.
\end{itemize}

Each Modelica file in the file-system is stored in UTF-8 format (defined by The Unicode Consortium; \url{https://unicode.org}).
A deprecated feature is that the file may start with the UTF-8 encoded BOM (byte order mark; \lstinline!0xef 0xbb 0xbf!); this is treated as white-space in the grammar.
Since the use of BOM is deprecated, tools can ignore any BOM when reading, and it is recommended to never write it.

\begin{nonnormative}
Tools may also store classes in data-base systems, but that is not standardized.
\end{nonnormative}


\subsection{Directory Hierarchy Mapping}\label{mapping-a-package-class-hierarchy-into-a-directory-hierarchy-structured-entity}\label{directory-hierarchy-mapping}

A directory shall contain a node, the file \filename{package.mo}.
The node shall contain a \lstinline[language=grammar]!stored-definition! that defines a class \lstinline!A! with a name matching the name of the structured entity.

\begin{nonnormative}
The node typically contains documentation and graphical information for a package, but may also contain additional elements of the class \lstinline!A!.
\end{nonnormative}

A directory may also contain one or more sub-entities (directories or files).
The sub-entities are mapped as elements of the class defined by their enclosing structured entity.
Two sub-entities shall not define classes with identical names

\begin{example}
If directory \filename{A} contains the three files \filename{package.mo}, \filename{B.mo} and \filename{C.mo}, the classes defined are \lstinline!A!,
\lstinline!A.B!, and \lstinline!A.C.!
\end{example}

\begin{example}
A directory shall not contain both the sub-directory \filename{A} and the file \filename{A.mo}.
\end{example}

In order to preserve the order of sub-entities it is advisable to create a file \filename{package.order} where each line contains the name of one class or constant (using its Modelica \lstinline!IDENT! form).
If a \filename{package.order} is present when reading a structured entity the classes and constants are added in this order; if the contents does not exactly match the classes and constants in the package, the resulting order is tool specific and a warning may be given.
Classes and constants that are stored in \filename{package.mo} are also present in \filename{package.order} but their relative order should be identical to the one in \filename{package.mo} (this ensures that the relative order between classes and constants stored in different ways is preserved).


\subsection{Single File Mapping}\label{mapping-a-package-class-hierarchy-into-a-single-file-nonstructured-entity}\label{single-file-mapping}

When mapping a package or class-hierarchy to a file (e.g., the file \filename{A.mo}), that file shall only define a single class \lstinline!A! with a name matching the name of the nonstructured entity.
In a file hierarchy the files shall have the extension \filename{.mo}.

A \filename{.mo} file defining more than one class cannot be part of the mapping
to file-structure and it is an error if it is loaded from the
\lstinline!MODELICAPATH!.


\subsection{The within Clause}\label{the-within-clause}

A \lstinline!within!-clause has the following syntax:
\begin{lstlisting}[language=grammar]
  within [ packageprefixname ] ";"
\end{lstlisting}%
\indexinline{within}
A non-top-level entity shall begin with a \lstinline!within!-clause which for the class defined in the entity specifies the location in the Modelica class hierarchy.
A top-level class may contain a \lstinline!within!-clause with no name.
For a sub-entity of an enclosing structured entity, the \lstinline!within!-clause shall designate the class of the enclosing entity; and this class must exist and must not have been defined using a short class definition.

\begin{example}
The subpackage \lstinline!Rotational! declared within \lstinline!Modelica.Mechanics! has the fully qualified name \lstinline!Modelica.Mechanics.Rotational!, which is formed by concatenating the \lstinline[language=grammar]!packageprefixname! with the short name of the package.
The declaration of \lstinline!Rotational! could be given as below:
\begin{lstlisting}[language=modelica]
within Modelica.Mechanics;
package Rotational // Modelica.Mechanics.Rotational
  $\ldots$
\end{lstlisting}
\end{example}


\section{External Resources}\label{external-resources}

In order to reference external resources from documentation (such as links and images in html-text) and/or to reference images in the \lstinline!Bitmap! annotation (see \cref{bitmap}).
Absolute URIs should be used, for example \filename{file:///} and the URI scheme \filename{modelica:/} which can be used to retrieve resources associated with a package.
According to the URI specification scheme names are case-insensitive, but the lower-case form should be used, that is \filename{Modelica:/} is allowed but \filename{modelica:/} is the recommended form.

The Modelica-scheme\index{Modelica!URI scheme}\index{URI!Modelica} has the ability to reference a hierarchical structure of resources associated with packages.
The same structure is used for all kind of resource references, independent of use (external file, image in documentation, bitmap in icon layer, and link to external file in the documentation), and regardless of the storage mechanism.

Any Modelica-scheme URI containing a slash after the package-name is interpreted as a reference to a resource.
The first \emph{segment} of the \emph{path} of the URI is interpreted as a fully qualified package name and the rest of the \emph{path} of the URI is interpreted as the path (relative to the package) of the resource.
Each storage scheme can define its own interpretation of the path (but care should be taken when converting from one storage scheme or when restructuring packages that resource references resolve to the same resource).
Any storage scheme should be constrained such that a resource with a given path should be unique for any package name that precedes it.
The second segment of the path shall not be the name of a class in the package given by the first segment.

As a deprecated feature the URI may start with \filename{modelica://} and use the host-part of the authority as the fully qualified package name.
That feature is widely used, but deprecated since host-names are generally case-insensitive.
\begin{nonnormative}
Examples of this deprecated feature would be \filename{modelica://Modelica/Resources/C.jpg} (referring to a resource) and \filename{modelica://Modelica.Blocks} (referring to a package).
These should be rewritten as \filename{modelica:/Modelica/Resources/C.jpg} and \filename{modelica:/Modelica.Blocks}.
\end{nonnormative}

When Modelica packages are stored hierarchically in a file-system (i.e., package \lstinline!A! in a directory \filename{A} containing \filename{package.mo}) the resource
\filename{modelica:/A/Resources/C.jpg} should be stored in the file \filename{A/Resources/C.jpg}, it is not recommend to use \filename{modelica:/A.B/C.jpg} for referencing resources; it could be stored in the file \filename{A/B/C.jpg} -- which is counter-intuitive if \lstinline!A.B! is stored together with \lstinline!A!.
When Modelica packages are stored in other formats a similar mapping should be defined, such that a resource with a given path should be unique for any package name that precedes it.
The second segment of the path shall not be the name of a class in the package given by the first segment.
As above for \filename{Modelica 3.2.1/package.mo}, i.e., resources starting from \filename{Modelica 3.2.1}, and \filename{modelica:/Modelica.Mechanics/C.jpg} is \filename{Modelica 3.2.1/Mechanics/C.jpg} -- regardless of whether \lstinline!Modelica.Mechanics! is stored in \filename{Modelica 3.2.1/package.mo}, \filename{Modelica 3.2.1/Mechanics.mo}, or \filename{Modelica 3.2.1/Mechanics/package.mo}.

For a Modelica-package stored as a single file, \filename{A.mo}, the resource \filename{modelica:/A/C.jpg} refers to a file \filename{C.jpg} stored in the same directory as \filename{A.mo}, but using resources in this variant is not recommended since multiple packages will share resources.

In case the name of the class contains quoted identifiers, the single-quote `\lstinline!`!' and any reserved characters (`\lstinline!:!', `\lstinline!/!', `\lstinline!?!', `\lstinline!\#!', `\lstinline![!', `\lstinline!]!', `\lstinline!@!', `\lstinline!!!', `\lstinline[mathescape=false]!\$!', `\lstinline!\&!', `\lstinline!(!', `\lstinline!)!', `\lstinline!*!', `\lstinline!+!', `\lstinline!,!', `\lstinline!;!', `\lstinline!=!') should be percent-encoded as normal in URIs.

\begin{example}
Consider a top-level package \lstinline!Modelica! and a class \lstinline!Mechanics! inside it, a reference such as \filename{modelica:/Modelica.Mechanics/C.jpg} is legal, while \filename{modelica:/Modelica/Mechanics/C.jpg} is illegal.
The references \filename{modelica:/Modelica.Mechanics/C.jpg} and \filename{modelica:/Modelica/C.jpg} must also refer to two distinct resources.
\end{example}


\section{Multilingual Descriptions}\label{multilingual-descriptions}\index{translation!multilingual libraries}

\begin{nonnormative}
Descriptive texts in a model or library are usually formulated in English.
This section describes how a tool can present the library in another language.
Translated Modelica text is provided by external files, so that no modification of the original Modelica text is required.
\end{nonnormative}

The texts in following Modelica constructs should be translated:
\begin{itemize}
\item description strings of component declarations and classes
\item strings in the following annotations:
\begin{itemize}
\item \lstinline!Text.string!, \lstinline!Text.textString!
\item \lstinline!missingInnerMessage!, \lstinline!obsolete!, \lstinline!unassignedMessage!
\item \lstinline!Dialog.group!, \lstinline!Dialog.tab!
\item
  \lstinline!Dialog.loadSelector.caption!, \lstinline!Dialog.loadSelector.filter!,
  \ifpdf\\\else\fi% Avoid comma ending up at beginning of wrapped line in PDF output.
  \lstinline!Dialog.saveSelector.caption!, \lstinline!Dialog.saveSelector.filter!
\item \lstinline!Documentation.info!, \lstinline!Documentation.revisions!
\item \lstinline!Figure.title!, \lstinline!Figure.caption!, \lstinline!Figure.group!, \lstinline!Plot.title!, \lstinline!Axis.label!, \lstinline!Curve.legend!
\item \lstinline!mustBeConnected!
\end{itemize}
\end{itemize}

\begin{nonnormative}
None of the translatable constructs can have any impact on simulation results.
\end{nonnormative}

Comments (delimited as well as rest-of-line) are not translated.
Only constructs given entirely by one or more concatenated string literals are translated, using nothing but the operator \lstinline!+! for concatenation.
In order to have parameter values as part of the texts the special substitution syntax is preferable (see \cref{text} and \cref{variable-replacements}), and translators need to be aware of these substrings in order to make good translations.

\begin{example}
Consider:
\begin{lstlisting}[language=modelica]
annotation($\ldots$, Text(string = "1st Frequency: %f1"),
               Text(string = "2nd Frequency: " + String(w2 / (2 * pi))), $\ldots$);
\end{lstlisting}
In this example only \lstinline!"1st Frequency is %f1."! can be translated; the second \lstinline!Text.string! doesn't consist entirely of concatenated string literals, and is hence completely excluded from translation.
\end{example}

The files to support translation must be provided along with the library.
They must be stored in the resources directory \filename{modelica://$\mathit{LibraryName}$/Resources/Language/}.

Two kind of files in \textcite{GettextManual} format have to be provided:
\begin{enumerate}
\item Template file \filename{$\mathit{LibraryName}$.pot} (Portable Object Template), one file per library which is stored as the resource \filename{modelica://$\mathit{LibraryName}$/Resources/Language/$\mathit{LibraryName}$.pot}.
It describes all translatable strings in the library, but does not contain any translations.
The pattern \filename{$\mathit{LibraryName}$} denotes the toplevel class name of the library.
\item One file for each supported language with the name \filename{$\mathit{LibraryName}$.$\mathit{language}$.po} (Portable Object), as the resource \filename{modelica://$\mathit{LibraryName}$/Resources/Language/$\mathit{LibraryName}$.$\mathit{language}$.po}.
This file is a copy of the associated template file, but extended with the translations in the specified language.
The pattern \filename{$\mathit{language}$} stands for the ISO 639-1 language code, e.g., \filename{de} or \filename{sv}.
\end{enumerate}

The detailed format of these files is described in \textcite{GettextManual}.
Use of translation files in other formats (including the binary MO file format) is not standardized in Modelica.
For Modelica translations, only the keywords \lstinline!msgctxt!, \lstinline!msgid! and \lstinline!msgstr! are used, meaning that a translation entry looks like this:
\begin{lstlisting}
#: $\mathit{filename}$:$\mathit{lineNumber}$
#, no-c-format
msgctxt $\mathit{messageContext}$
msgid $\mathit{messageIdentifier}$
msgstr $\mathit{messageTranslation}$
\end{lstlisting}
The restriction to a few keywords makes it easier for tools to support the format without relying on the implementation from \textcite{GettextManual}.

The use of \lstinline!no-c-format! ensures that translation tools will not parse \lstinline!"%class"! as the format specifier \lstinline!%c! followed by \emph{lass}.

\begin{nonnormative}
In the remainder of this section, several facts about the gettext specification are interleaved non-normatively for easy access to some of the gettext basics.
Always refer to the external gettext specification for full detail or in case of doubt.

All text strings are in double quotes and encoded with UTF-8 characters.
Comments start with an \lstinline!#! and are continued until the end of line.
Spaces outside strings are ignored and used as separators.

The files consist of a header and a body.
The header is marked with an empty \lstinline!msgid! and looks like this:
\begin{lstlisting}
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2019-03-15 10:52+0100\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
\end{lstlisting}
All general terms in the header should be replaced by specific information.

Following the header, there is one translation entry for each string to be translated.
It can start with an optional comment describing the location (file name and line number) of the text to translate.
Multiple occurences of the same string can be listed here, separated by space.
\end{nonnormative}

The $\mathit{messageContext}$ following the keyword \lstinline!msgctxt! shall be the full name of the Modelica class (e.g., \lstinline!"Modelica.Blocks.Math.Sin"!) where the text appears.
Short class definitions do not appear here.
Texts in such classes belong to the enclosing full class definition.

The text string which shall be translated is used as $\mathit{messageIdentifier}$ (following the \lstinline!msgid! keyword), and shall contain the original string from the Modelica code.
% Describe down-quoting and concatenation of Modelica string literals.
Note that if a \lstinline!msgid! string is given more than once in the same context, all occurrences are translated with the same (last) translation!

\begin{nonnormative}
The $\mathit{messageTranslation}$ (following the keyword \lstinline!msgstr!) is the translation of $\mathit{messageIdentifier}$ and is typically edited using special tools for translators.
In the template file this string is empty by definition.
If this is empty in a language specific file the $\mathit{messageIdentifier}$ may be used instead.
\end{nonnormative}

\begin{nonnormative}
Since in Modelica control sequences also start with a backslash and another backslash is used to use sequences literally or to hide double quotes, no change is required here.
But Modelica allows strings to go over more than one line, gettext does not.
Therefore, line breaks in Modelica must be encoded with \lstinline!"\n"! for gettext.

In order to avoid long lines in the translated strings (following \lstinline!msgid! or \lstinline!msgstr!), strings may be split into smaller parts given on consecutive lines.
E.g., the Modelica description
\begin{lstlisting}
"A
B\"C" + "D\nE"
\end{lstlisting}
evaluates to:\par
\hspace{1em}\begin{minipage}{0.5\textwidth}
A\\
B"CD\\
E
\end{minipage}\par
which in the translation entry looks like:
\begin{lstlisting}
msgid ""
"A\n"
"B\"CD\n"
"E"
\end{lstlisting}
\end{nonnormative}

\begin{example}
Consider a simple sine-source:
\begin{lstlisting}[language=modelica]
within MyPackage.Sources;
model Sine "Sine"
  parameter Frequency f=2 "Frequency";
  RealOutput y=sin(2*pi*f*time); // Relying on imported types
  /* Could add details. Note that this is not translated */
  annotation(Icon(graphics={Text(extent={{0,0},{40,40}},
                        textString="Frequency: %f")}));
end Sine;
\end{lstlisting}
The entries for translating this model into Swedish could look like this:
\begin{lstlisting}
#: MyPackage/Sources/package.mo:10126
#, no-c-format
msgctxt "MyPackage.Sources.Sine"
msgid "Sine"
msgstr "Sinus"
#: MyPackage/Sources/package.mo:10127
#, no-c-format
msgctxt "MyPackage.Sources.Sine"
msgid "Frequency"
msgstr "Frekvens"
#: MyPackage/Sources/package.mo:10131
#, no-c-format
msgctxt "MyPackage.Sources.Sine"
msgid "Frequency: %f"
msgstr "Frekvens: %f"
\end{lstlisting}
\end{example}

\begin{nonnormative}
To support the translation of these strings a number of free and commercial tools exist in context of GNU gettext.
\end{nonnormative}