Default Translatable XML Documentation

1. Introduction

FirstSpirit TranslationStudio uses FirstSpirit’s external synchronisation feature to generate a translatable xml file and to import a translated xml file into FirstSpirit again. Since not all elements need to be considered by you or a translator, this document will examine each input component and explain which parts might be omitted.

2. Input Components Which Must Not Be Translated

The following input components might be ignored in general.

CMS_INPUT_CHECKBOX
CMS_INPUT_COMBOBOX
CMS_INPUT_RADIOBUTTON
FS_DATASET
CMS_INPUT_DATE
CMS_INPUT_NUMBER
FS_REFERENCE
CMS_INPUT_LIST
FS_INDEX
CMS_INPUT_TOGGLE

2.1. CMS_INPUT_CHECKBOX

A checkbox component stores a specific value defined in the form template. Therefore, it must not be changed.

<FIELD name='CMS_INPUT_CHECKBOX'>
    <SEL>
        <VALUE>VALUE</VALUE>
    </SEL>
</FIELD>

2.2. CMS_INPUT_COMBOBOX

A combobox component stores a specific value defined in the form template. Therefore, it must not be changed.

<FIELD name='CMS_INPUT_COMBOBOX'>
    <SEL>
        <VALUE>VALUE</VALUE>
    </SEL>
</FIELD>

2.3. CMS_INPUT_RADIOBUTTON

A radio button component stores a specific value defined in the form template or a dataset id. Therefore, it must not be changed.

<FIELD name='CMS_INPUT_RADIOBUTTON'>
    <SEL>
        <VALUE>VALUE</VALUE>
    </SEL>
</FIELD>

2.4. FS_DATASET

A dataset component stores a specific dataset id which is used to access the respective dataset. To translate the respective dataset you have to submit the record instead. This component value must not be changed.

<FIELD name='FS_DATASET'>
    <VALUE uid="requests">
        <GID>60b22a5d-27e0-42d5-a430-8d67457a1654</GID>
    </VALUE>
</FIELD>

2.5. CMS_INPUT_DATE

A date component stores a specific date as numeric value. Consequently, it does not need to be translated.

<FIELD name='CMS_INPUT_DATE'>
    <DATE>1475228036000</DATE>
</FIELD>

2.6. CMS_INPUT_NUMBER

A number component stores a specific numeric value. Consequently, it does not need to be translated.

<FIELD name='CMS_INPUT_NUMBER'>
    <FIG>12345</FIG>
</FIELD>

2.7. FS_REFERENCE

A reference component stores a specific uid. Consequently, it does not need to be translated.

<FIELD name='FS_REFERENCE'>
    <UID>test</UID>
    <UIDTYPE>SITESTORE_LEAF</UIDTYPE>
    <REMOTE/>
</FIELD>

2.8. CMS_INPUT_LIST

A list component stores selections from a given list defined in the form template or a database. Consequently, it does not need to be translated.

<FIELD name='CMS_INPUT_LIST'>
    <SEL>
        <VALUE>VALUE</VALUE>
    </SEL>
</FIELD>

2.9. FS_INDEX

A index component stores records from a given database table. The element provides all data required to identify the respective records and if you want to translate the record, you have to submit it manually. Thus, this component does not need to be translated.

<FIELD name='FS_INDEX'>
    <INDEX>
        <RECORD>{"schema":"Products","gid":"00000000-0000-0000-ffff-ff041bf0d200","table":"Products"}</RECORD>
        <RECORD>{"schema":"Products","gid":"00000000-0000-0000-ffff-feaf7d53b88c","table":"Products"}</RECORD>
        </INDEX>
</FIELD>

2.10. CMS_INPUT_TOGGLE

A toggle component stores selections from a given list defined in the form template or a database. Consequently, it does not need to be translated.

<FIELD name='CMS_INPUT_TOGGLE'>
    <STATE>true</STATE>
</FIELD>

3. Translatable Input Components

Translatable input components might be divided into 3 categories:

Simple input components
Input components containing xml tags
Complex components

3.1. Simple input components

Text based input components are simple in their format and can be translated easily.

CMS_INPUT_TEXT
CMS_INPUT_TEXTAREA
CMS_INPUT_IMAGEMAP

3.1.1. CMS_INPUT_TEXT

A text component stores a simple string and does contain XML tags in the first place. The text inside the TEXT tag is translatable.

<FIELD name='CMS_INPUT_TEXT'>
    <TEXT>Lore ipsum dolor sit...</TEXT>
</FIELD>

3.1.2. CMS_INPUT_TEXTAREA

A textarea component stores a simple string and does contain XML tags in the first place. The text inside the TEXT tagtag is translatable.

<FIELD name='CMS_INPUT_TEXTAREA'>
    <TEXT>Lore ipsum dolor sit...</TEXT>
</FIELD>

3.2. Input components containing xml tags

Some input components might contain additional xml tags as part of the translatable content. The xml structure has to be regarded when translating the respective component value.

CMS_INPUT_DOM
CMS_INPUT_DOMTABLE

3.2.1. CMS_INPUT_DOM

A dom component stores a formatted text and uses xml tags to mark those parts. The content might differ depending on the formats available and on the style formats available.

<FIELD name='CMS_INPUT_DOM'>
    <DOM>
        <p>Lore <b>ipsum</b> dolor sit...</p>
        <p>Lore ipsum dolor <i>sit...</i></p>
        <p>Lore ipsum <CMS_LINK linktemplate="textlinkexternal" type="genericLink"><TEMPLATECONTENT><CMS_VALUE name="ref"><LANG id="§"  set="1"><TEXT>http://www.idmedia.com</TEXT></LANG></CMS_VALUE><CMS_VALUE name="text"><LANG id="§" set="1"><TEXT>dolor</TEXT></LANG></CMS_VALUE><CMS_VALUE name="linktemplate"><LANG id="§" set="1"><SEL><VALUE>textlinkexternal.standard</VALUE></SEL></LANG></CMS_VALUE></TEMPLATECONTENT></CMS_LINK> sit...</p>
    </DOM>
</FIELD>

In this example, the dom element stores 3 paragraphs each enclosed by a p tag. The first paragraph uses b to print a bold text whereas paragraph two uses an i tag to print a word in italics. The third paragraph is more complex as it contains a link element. The mechanism is similar, as the linked part is enclosed by a CMS_LINK tag.

The content of the CMS_LINK tag depends on its implementation in FirstSpirit. In the example above, the following code is provided:

<CMS_LINK linktemplate="textlinkexternal" type="genericLink">
    <TEMPLATECONTENT>
        <CMS_VALUE name="ref">
            <LANG id="§"  set="1">
                <TEXT>http://www.idmedia.com</TEXT>
            </LANG>
        </CMS_VALUE>
        <CMS_VALUE name="text">
            <LANG id="§" set="1">
                <TEXT>dolor</TEXT>
            </LANG>
        </CMS_VALUE>
        <CMS_VALUE name="linktemplate">
            <LANG id="§" set="1">
                <SEL>
                    <VALUE>textlinkexternal.standard</VALUE>
                </SEL>
            </LANG>
        </CMS_VALUE>
    </TEMPLATECONTENT>
</CMS_LINK>

Each input component of the respective link template linkexternal is enclosed by a CMS_VALUE tag. The <LANG id='§'> … </LANG> tag specifies its value to be language independent since the dom input component is language specific itself. The TEXT tag specifies the translatable content, whereas the SEL tag specifies an input component which does not need to be translated by any translator.

3.2.2. CMS_INPUT_DOMTABLE

A domtable component stores a table using HTML table tags. The content might differ depending on the formats available and on the style formats available.

<FIELD name='CMS_INPUT_DOMTABLE'>
    <table>
        <tr>
            <td>Lore ipsum dolor sit...</td>
            <td>Lore ipsum <i>dolor</i> sit...</td>
        </tr>
        <tr>
            <td>Lore ipsum dolor sit...</td>
            <td>Lore <b>ipsum</b> dolor sit...</td>
        </tr>
    </table>
</FIELD>

The HTML table tags must not be changed. Only the text enclosed by a td tag is translatable. Importantly, the text might contain further tags as shown above.

3.2.3. CMS_INPUT_IMAGEMAP

An imagemap component only has limited translatable values. Only link sections contain translatable content and depend on the respective link template implementation.

<FIELD name='CMS_INPUT_IMAGEMAP'>
    <REF>media:data_analyzing</REF>
   <ALT/>
   <REMOTE/>
   <RESOLUTION>ORIGINAL</RESOLUTION>
   <AREAS>
      <AREA coordinates="241,121,341,221" shape="RECT">
         <LINK>
            <CMS_LINK linktemplate="productlink" type="genericLink">
               <TEMPLATECONTENT>
                  <CMS_VALUE name="lnk_text">
                     <LANG id="§" set="1">
                        <TEXT>Link Text</TEXT>
                     </LANG>
                  </CMS_VALUE>
                  <CMS_VALUE name="lnk_product">
                      <LANG id="§" set="1">
                         <VALUE uid="Products.products">
                            <GID>
                               00000000-0000-0000-ffff-fe6a2d03fd00
                            </GID>
                         </VALUE>
                     </LANG>
                  </CMS_VALUE>
              </TEMPLATECONTENT>
            </CMS_LINK>
         </LINK>
      </AREA>
   </AREAS>
</FIELD>

In the example above, the linktemplate productlink contains two input components of which only link_text contains a translatable TEXT node. All other attributes and xml nodes must not be translated.

3.3. Complex Components

There are two types of complex components.

FS_LIST
FS_CATALOG

These input components are lists which can contain a huge amount of list entries which may vary depending on the templates used.

3.3.1. FS_LIST

A FS_LIST element has the following basic nodes:

<FIELD name='FS_LIST'>
    <DATA>
        <ENTRY id="{number}" template="{template uid}">
            {template data}
        </ENTRY>
    </DATA>
</FIELD>

Importantly, the ENTRY node attributes must never be changed.

If the FS_LIST component lists database records, the component must not be changed, since it only contains id references of the respective database records, for example:

<FIELD name='FS_LIST'>
    <DATA>
        <ENTRY id="1794" template="Products.products">
            <GID>00000000-0000-0000-ffff-fe77bb830708</GID>
        </ENTRY>
        <ENTRY id="1856" template="Products.products">
            <GID>00000000-0000-0000-ffff-fe6a2d03fd00</GID>
        </ENTRY>
    </DATA>
</FIELD>

If the FS_LIST component lists section or link templates, each ENTRY node might provide considerable amount of data, for example:

<FIELD name='FS_LIST'>
    <DATA>
        <ENTRY id="1" template="textlinkexternal">
            <TEMPLATECONTENT>
                <CMS_VALUE name="ref">
                    <LANG id="§" set="1">
                        <TEXT>http://www.idmedia.com</TEXT>
                    </LANG>
                </CMS_VALUE>
                <CMS_VALUE name="text">
                    <LANG id="§" set="1">
                        <TEXT>i-d media AG</TEXT>
                    </LANG>
                </CMS_VALUE>
                <CMS_VALUE name="linktemplate">
                    <LANG id="§" set="1">
                        <SEL>
                            <VALUE>textlinkexternal.standard</VALUE>
                        </SEL>
                    </LANG>
                </CMS_VALUE>
            </TEMPLATECONTENT>
        </ENTRY>
    </DATA>
</FIELD>

Each ENTRY node contains a TEMPLATECONTENT node. This, in turn, has many CMS_VALUE nodes marking a specific input component. In this example, only the text enclosed by a TEXT node provides translatable content. All other nodes must not be changed.

3.3.2. FS_CATALOG

A FS_CATALOG element has the following basic nodes:

<FIELD name='FS_CATALOG'>
    <CATALOG>
        <CARD id="{number}" template="{template uid}" type="{store type}">
            {template data}
        </CARD>
    </DATA>
</FIELD>

Importantly, the CARD node attributes must never be changed. The template data nodes depend on the template chosen, for example:

<FIELD name='FS_CATALOG'>
    <CATALOG>
        <CARD id="bd252215-206e-4e70-84d5-715c8a0b9c40" template="textpicture" type="TEMPLATESTORE">
            <TEMPLATECONTENT>
                <CMS_VALUE name="st_headline">
                    <LANG id="DE" set="1">
                        <TEXT>Lore ipsum dolor sit...</TEXT>
                    </LANG>
                    <LANG id="EN" set="0"/>
                </CMS_VALUE>
                <CMS_VALUE name="st_text">
                    <LANG id="DE" set="1">
                        <DOM>
                            <p>Lore ipsum <b>dolor</b> sit...</p>
                        </DOM>
                    </LANG>
                    <LANG id="EN" set="0"/>
                </CMS_VALUE>
            </TEMPLATECONTENT>
        </CARD>
    </CATALOG>
</FIELD>

Each CARD node contains a TEMPLATECONTENT node. This, in turn, has many `CMS_VALUE nodes marking a specific input component. In this example, only the text enclosed by a TEXT or DOM node provides translatable content. All other nodes must not be changed.

4. Changing the XML Structure

It is possible to change the xml structure. Yet, the structure of each component must be as provided by the system since the import might break if the structure is incorrect. You may remove certain fields which cannot be translated and FirstSpirit TranslationStudio provides Hooks to do exactly that. However, fields which cannot be translated but are part of a list entry must never be removed. Only top level fields can be removed. If fields are missing, the source language field value will be used at the time of the import.

5. Translatable XML

TranslationStudio uses the xml provided by FirstSpirit and adds certain nodes to it in order to amalgate page, section and entity data.

5.1. Generic Translateble XML Structure

Each translatable xml containing pages and sections has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<ELEMENTS>
</ELEMENTS>

Each child of the ELEMENTS tag might bei either BASICPAGE or ENTITIES.

5.2. Translatable Pages and Sections

Each translatable xml containing pages and sections has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<ELEMENTS>
   <BASICPAGE DSTLANG="DE" ID="164467" PROJECTID="11" SRCLANG="EN" TASKID="15682" TASKLISTID="119686" UID="mithras_home_21" WORKFLOW="1786" type="page">
      <PARAGRAPHS>
         <PARAGRAPH DSTLANG="DE" GCATASKID="15682" GCATASKPAGEID="119686" ID="164477" PROJECTID="11" SRCLANG="EN" UID="tag_cloud__local_">
            <FIELDS>
               <FIELDSINDEP>
                   <FIELDS> ... </FIELDS>
               </FIELDSINDEP>
               <FIELDSDEP>
                   <FIELDS> ... </FIELDS>
               </FIELDSDEP>
            </FIELDS>
         </PARAGRAPH>
      </PARAGRAPHS>
      <FIELDS>
         <FIELDSDEP>
            <FIELDS> ... </FIELDS>
         </FIELDSDEP>
         <FIELDSINDEP>
            <FIELDS> ... </FIELDS>
         </FIELDSINDEP>
      </FIELDS>
      <NAVIGATION>
       <NAVIGATION_ENTRY>
        <PAGEREF id="20391" uid="homepage">
            <DISPLAYNAME>
                <TEXT>...</TEXT>
            </DISPLAYNAME>
            <KEYWORDS>
                <TEXT/>
            </KEYWORDS>
            <SITEMAPLABEL>
                <TEXT/>
            </SITEMAPLABEL>
        </PAGEREF>
        <FOLDER id="22038" uid="homepage">
            <COMMENT>
                <TEXT/>
            </COMMENT>
            <KEYWORDS>
                <TEXT/>
            </KEYWORDS>
            <MENULABEL>
                <TEXT>...</TEXT>
            </MENULABEL>
            <TREELABEL>
                <TEXT>...</TEXT>
            </TREELABEL>
        </FOLDER>
     </NAVIGATION_ENTRY>
    </NAVIGATION>
   </BASICPAGE>
</ELEMENTS>

Each BASICPAGE node represents one page with all its sections. Each page section is listed as PARAGRAPH as child of the PARAGRAPHS node. The page form data itself is a direct child node of BASICPACE.

The translatable form data is categorised as either language independent or language dependent and listed in the respective node (FIELDSINDEP or FIELDSDEP). Importantly, these nodes have a child FIELDS node. This last node contains all translatable FIELD nodes of the input form components as listed above and only these FIELD nodes contain translatable data. All parent nodes are used to organise and structure the data.

5.3. Translatable Entities

Each translatable xml containing entities has the following structure:

<ELEMENTS>
    <ENTITIES DSTLANG="DE" SRCLANG="EN" alterExisting="true" content2id="1610" project="11" schema="Products" table="Glossary" type="entity">
        <ENTITY fs_id="839" task="15680" taskpage="119686" workflow="1787">
            <COLUMN isList="false" name="Term_DE">...</COLUMN>
            <COLUMN isList="false" name="Description_DE">...</COLUMN>
        </ENTITY>
    </ENTITIES>
</ELEMENTS>

Each ENTITIES node contains all entities belonging to the same Content2 element. Each ENTITY node provides all columns with their respective value.

6. List of tag names that will not be translated

The following list of tag names should not be translated sine they usually represent technical values. Each tag name is either a direct child or a FIELD node or a child of other components (see list above).

<STATE>...</STATE>
<CATALOG>...</CATALOG>
<SEL>...</SEL>
<DATE>...</DATE>
<FIG>...</FIG>
<UID>...</UID>
<UIDTYPE>...</UIDTYPE>
<REMOTE>...</REMOTE>
<INDEX>...</INDEX>
<REF>...</REF>
<ALT>...</ALT>
<RESOLUTION>...</RESOLUTION>
<VALUE>
        <GID>...</GID>
</VALUE>
<DATA>
        <ENTRY>
                <GID>...</GID>
        </ENTRY>
</DATA>

TranslationStudio hides these fields using a FSTS_KEEP_CONTENT node.

7. Identifying translatable nodes

The translatable XML hides all content irrelevant for translation. Furthermore, the only translatable text nodes are either

<TEXT>...</TEXT>
<DOM>...</DOM>
<table>...</table>
<DISPLAYNAME>...</DISPLAYNAME>
<KEYWORDS>...</KEYWORDS>
<SITEMAPLABEL>...</SITEMAPLABEL>
<COMMENT>...</COMMENT>
<MENULABEL>...</MENULABEL>
<TREELABEL>...</TREELABEL>

Please note: DOM and table will have HTML content and child nodes.

NAVIGATION entries will only have TEXT nodes.

8. Changing the XML Structure using Hooks

TranslationStudio requires the basic format above in order to import the translations successfully. However, you may implement a Hook to transform this XML before it will be transferred to a translation memory system or before it will be stored in the translated directory and imported again. Please consult the Hook documentation for further information.