Customizing Akoma Ntoso: modularization, restrictions, extensions
Appendix A: Translations of Akoma Ntoso
The vocabulary of Akoma Ntoso is mostly in English (except for the root element akomaNtoso, which is in Akan, a language from Ghana). This decision was taken to improve its recognizability and diffusion of the standard .
Situations may exist, on the other hand, that require a localized version of the Akoma Ntoso vocabulary in a different language. This implies creating a full set of terms for element and attribute names in a different language than English.
It has to be fully appreciated that, an XML document that uses element names and attribute names that do not belong to the Akoma Ntoso schema cannot be considered an Akoma Ntoso document. By translating the schema you are getting out of the scope of the Akoma Ntoso language/standard and your documents will not be Akoma Ntoso compliant.
Yet there are some translations that are better than others for an Akoma Ntoso environment. The basic rule for translating Akoma Ntoso is that any XML document valid for the translated version of Akoma Ntoso must be translated back into a valid Akoma Ntoso document by changing only element and attribute names.
We need therefore to introduce a class of schemas (and of documents that are validated by them) that, while not being Akoma Ntoso, are close enough to it to be taken into consideration.
The purpose of this section, therefore, is to list first the requirements for a correct translation, and then to describe a simple tool (an XML file and an XSLT stylesheet) that can be used to generate correct translations.
An official translation of Akoma Ntoso must target a specific namespace that cannot be the usual Akoma Ntoso namespace, but must still be controlled and not arbitrary. For this reason, official translations of Akoma Ntoso must be associated to namespaces of the form:
where language is a three-letter code denoting the language according to ISO 639-2 alpha-3 (e.g., English is eng, Italian is ita, German is ger, etc.).
By construction, the full Akoma Ntoso is the English version of Akoma Ntoso, and thus http://www.akomantoso.org/20/eng is defined as equivalent to http://www.akomantoso.org/20.
For a schema to be a correct translation of Akoma Ntoso, there must be a conversion mechanism from the translated back into the main Akoma Ntoso vocabulary. This implies that there is a one-to-one mapping between terms of the vocabulary of Akoma Ntoso and terms of the translated vocabulary. These terms include element names, attribute names and enumerations of allowed values in attributes.
Not all terms in the Akoma Ntoso vocabulary can be translated. In particular, the name of the root element akomaNtoso must be maintained in all translations, and HTML elements and attributes must be maintained in all translations. These include, among others, elements such as p, b, i, table, or img, as well as attributes such as id, href, class and title.
Translated terms should be correct and currently used terms belonging either to the general language or to the technical and/or juridical vocabulary of the local language. Terms that are composed of exactly one word must be in lowercase, and compositions of different words must be in camelCase, i.e., the term is the collapse of (i.e., the removal of the spaces separating) the words, where the first word is lowercase and all subsequent words have the initial in uppercase.
Finally, no translations should be performed for the two fundamental acronyms that appear in Akoma Ntoso terms: “FRBR” (which stands for “Functional Requirement of Bibliographic Record”), that is the conceptual model on which the document organization of Akoma Ntoso is based; and “TLC” (which stands for “Top Level Class”), that is the ontological framework to connect Akoma Ntoso documents and Semantic Web ontologies. The translation of terms that contain either of the two acronyms must contain them as well.
Other translatable terms
The main Akoma Ntoso schema contains other terms, basically names for complex types, simple types, element groups and attribute groups. There are no requirements on the translation of these terms, but since they do not appear in the final XML document. It is therefore a local decision whether these terms are actually translated or not.
Tools for Akoma Ntoso translations
The main problem with managing Akoma Ntoso translations is the alignment between the original and the translated schema whenever a new release of the language is published. Generating the translation by editing directly the schema is an easy way to do the translation, but requires that it be done again, and exactly, every time a new release of the language becomes available.
We describe here a mapper that simplifies the work for the translators, reduces the possibilities of error or inconsistencies in the translation, and reduces the workload of the synchronization of the translation. The mapper is based on a two-entry vocabulary that lists all translatable terms and their translations. This is an XML file as the following:
<source xml:lang="eng" namespace="http://www.akomantoso.org/20" />
<dest xml:lang="ita" namespace="http://www.akomantoso.org/20/ita" />
<element source="FRBRExpression" dest="espressioneFRBR" />
<element source="FRBRItem" dest="elementoFRBR" />
<element source="FRBRManifestation" dest="manifestazioneFRBR" />
<element source="FRBRWork" dest="operaFRBR" />
<element source="FRBRalias" dest="aliasFRBR" />
<element source="FRBRauthor" dest="autoreFRBR" />
<attribute source="actor" dest="attore" />
<attribute source="alternativeTo" dest="alternativoA" />
<attribute source="as" dest="come" />
<attribute source="breakat" dest="aCapoPresso" />
<enumeration source="after" dest="dopo" />
<enumeration source="agreeing" dest="inAccordo" />
<enumeration source="amendment" dest="emendamento" />
Two applications (really XSLT stylesheets) are used to generate automatically the translated schema. The tool works in three steps:
- In the first step, the original Akoma Ntoso schema is used with the MapGenerator.xsl stylesheet (see Appendix A), that creates the XML map file as shown before, but with no translated term (or, rather, with an identity translation from English to English). This tool automatically excludes non-translatable terms as specified in section 5.2.
- In the second step, an expert in the local language fills in the translated term for each item of the map. This file is then saved and made available to the next step.
- In the third step, the original Akoma Ntoso schema is used again, but with the Map.xsl stylesheet (see Appendix B) and the newly created map file. This stylesheet creates a valid XML Schema that is identical to the original Akoma Ntoso schema, but defines elements, attributes and enumerated values as specified in the mapping rather than as in the original.
The end result is an XML Schema with the correct namespace, all non-translatable terms unchanged, and all translatable terms translated wherever they appear in the original schema. No translation is performed of the name of complex types, simple types, element groups and attribute groups.