Defining Items

Avatar
Nienke
Follow

After reading this you will know how to structure the content you exchange with LivewordsFlow and achieve the best translation quality through the use of our API.

Our API only accepts XML. There are two ways of formatting that XML. 

  1. Use our predefined format and our XSD.
  2. Livewords can also be configured to process a variety of XML formats.

XSD based (standard)

When you have full control over the data format you send LivewordsFlow. We recommend you use and follow the XSD. You can use our example  that conforms to the XSD for guidance or read the instructions below to learn more about the interpretation of xml.

Source settings corresponding to this xml structure:

{
"type" : "APIFeed",
"cdataLocations" : [ ],
"clientType" : "default",
"excludeLocations" : [ ],
"ignoreLocations" : [ "items/item/images/**", "/items/item/labels/**" ],
"imageExpression" : {
"/items/item/images/image" : "imageElement.getText()"
},
"includeLocations" : [ "/items/item/**" ],
"itemLocations" : [ "/items/item" ],
"labelExpression" : {
"/items/item/labels/label" : "getText()"
},
"locationExpression" : {
"/items/item" : "feedItemElement.getAttributeValue('id')"
},
"namespaces" : { },
"publishComputerTranslations" : false,
"splittingInlineHtmlTags" : false,
"textLocationTypes" : {
"ALL" : "text/html"
},
"titleExpression" : { },
"useComputerTranslations" : false,
"writeEmptyItems" : true,
"writeIncompleteItems" : true,
"writeUntranslatedElements" : true
}

 

Configured xml (advanced)

LivewordsFlow also has the possibility for non-normative usage. Meaning there is no specific validity constraints like an XSD or DTD. LivewordsFlow can work with a variety of XML formats. See Item Syntax further down to read more about what syntax of the XML LivewordsFlow can handle. To ensure an optimal exchange between the originating system and LivewordsFlow there are a few things to keep in mind.

  1. The XML structure used must be readable by LivewordsFlow to import into our Workflow. As well as by the originating system when translations are returned.

  2. The content needs to be in the right context for the translator.

That is why LivewordsFlow introduced the term item. Every xml exchanged with LivewordsFlow can consist of one or more items.

A few basics on the XML document containing the items:

  • It has to contain valid XML, an XML declaration and a parent element, example is the <catalog> tag in the example below . The character encoding of the XML document must be UTF-8.
  • A multilingual xml document must be language-tagged. A language tag needs to be present on elements that need to be extracted.

The source feed does not need to contain new text only. LivewordsFlow will figure out the difference in content and update the translation workflow accordingly.

Defining Feed Items

An item in LivewordsFlow has the following characteristics:

  • an item is the object that moves through the workflow;

  • an item can be assigned a deadline, priority and other processing features;

  • an item can be previewed;

  • an item is the smallest aggregation of content that is still meaningful if received back completely translated, e.g. a page, product or a promotion-banner.

Items are configured in LivewordsFlow on the source level. Items are specified by a path-like (or Xpath-like) expression such as /catalog/product that divides the XML in a sequence of items. When LivewordsFlow parses the content and finds an XML element that matches with /catalog/product, it will process the element as an item.

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
  <product>
    ...
  </product>
  <product>
    ...
  </product>
  ...
  <product>
    ...
  </product>
</catalog>

In the above example every product will represent an item in LivewordsFlow.

Item syntax

The encoding has to be UTF-8.

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

Items in LivewordsFlow have a title and a location. If you do not configure this in the source settings they will be automatically generated. The location is also the unique identifier for an item. A location could be /catalog/product/11 and a title could be Blue Hoodie with Stripes. The title can be taken from an attribute on the item level or from within an element.

<product id="11" title="Blue Hoodie with stripes">
</product>

<product id="11">
  <title>Blue Hoodie with stripes</title>
</product>

Text in elements can be translated. Text in attribute values can not. The name of the language attribute is defined in the xml namespace (xml:lang). Language attributes are optional and should be used in the entire document or not at all. As an example, the language tags below are used on different levels. Directly on the element or on one of the parent elements. Only one language can be choosen as the source language to transate. So even if more language tags are added, only one can be used.

<product id="11">
  <title xml:lang="en">Blue Hoodie with stripes</title>
  <title xml:lang="fr">Hoodie blue a rayures</title>
  <short-description xml:lang="en">
    <value>This hoodie is blue and has stripes</value>
  </short-description>
</product>

Elements can contain html content. The html content will be split up in LivewordsFlow so that only the text within the elements/attributes will be translated. Test in html attributes can also be translated, like title or alt tags. Images can be replaced.

<description xml:lang="en">
  This hoodie has a blueish color &amp; 
  has stripes over the back.&lt;br&gt;It is mostly
  warn by tough people.
</description>

Elements can contain CDATA elements

<product id="11">
  <title xml:lang="en"><![CDATA[Blue Hoodie with 
   stripes]]></title>
  <short-description xml:lang="en">
    <![CDATA[This hoodie is blue and has stripes]]>
  </short-description>
  <description xml:lang="en">
    <![CDATA[This hoodie has a blueish color &
     has stripes over the back.<br>It
    is mostly warn by tough people.]]>
  </description>
</product>

The possible target languages are defined in LivewordsFlow source configuration. You can send item for translation to a subset of these languages by using target-language request parameter. If you use client type demandware in source configuration you can deviate from the default settings by adding a custom-attribute to define a selection of the possible target languages per item. 

<product id="11">
  <custom-attribute attribute-id="livewords:target-lang">
    <value>nl</value>
    <value>en-UK</value>
    <value>fr</value>
  </custom-attribute>
</product>

Items can be excluded through the source configuration or by adding a custom attribute livewords:skip. This is good practice if you want the content manager to manage this in the originating system.

<product id="11">
  <custom-attribute attribute-id="livewords:skip">true
  </custom-attribute>
</product>

A preview-url can also be added

<product id="11" preview-url="http://domain/to/product-preview">
...

Images can be extracted from the item to be shown to the translator during translation.

<product>
  <images>
    <image>http://domain/image1.jpg</image>
    <image>http://domain/image1.jpg</image>
    <image>http://domain/image1.jpg</image>
  </images>
</product>

The element names are free of choice. There is no XSD/DTD validation. As long as it is valid xml. You must take into account that path like expressions do not always work if elements are not descriptive enough. In the below example, the elements are named differently but they do all contain a describing attribute. That way it is still possible to for example exclude /content-export/element/element[@type='online'] from the export.

<element preview-url="http://domain/to/product-preview" type="product" id="11" >
  <element type="title" xml:lang="en">Blue Hoodie with stripes</element>
  <element type="short-description" xml:lang="en">This hoodie is blue and has stripes</element>
  <element type="description" xml:lang="en">
    This hoodie has a blueish color &amp; has stripes over the back.&lt;br&gt;It is mostly
    warn by tough people.
  </element>
  <element type="online">false</element>
  <custom-attribute attribute-id="livewords:target-lang">
    <value>nl</value>
    <value>en-UK</value>
    <value>fr</value>
  </custom-attribute>
  <custom-attribute attribute-id="livewords:skip">true</custom-attribute>
  <elements type="images">
    <element>false</element>
    <element>false</element>
    <element>false</element>
  </elements>
</element>

Multiple items can be defined in a source feed: /content-export/product /content-export/footer-element /content-export/element[@type='product'] Any content that is not within an element will be sent back as is unless it is explicitly removed.

<content-export>
  <product>...</product>
  <footer-element>...</footer-element>
  <element type="product">...</element>
</content-export>

Standard Language Codes

LivewordsFlow uses language codes as specified in RFC 1766, which defines language codes that may denote a language only. Ex.en or denote a language as used in a geographical area like Great Britain English, indicated as en-GB. In general a language code contains a primary tag and an optional subtag. If a subtag is present, the primary tag and the subtag are separated with a dash -. So, the codes we’ll use the most have this structure.

primarytag  // “en”, “nl”, “de”, “zh”, “x-default”
primarytag–subtag // “en–GB”, “en–US”, “zh–TW”, “zh–CN”

Letters in the primary tag designate languages according to ISO 639 and letters in the subtag designate countries according to ISO3166.

...
  <product product-id="P345562">
    <title xml:lang="en-US">Washington Brown Plain</title>
  </product>
 ...
Have more questions? Submit a request

Comments