Fields
Content request are built up of one or more fields. Fields are used both to request a localization of a text, the creation of a text and to deliver internal or contextual information needed to work with a content request.
A field object contains the following values:
| Name | Type | Description |
|---|---|---|
id |
string | Identifier of the field, use this for retrieval of field data and querying of requests. |
name |
string | Human readable name of the field. Optional, id is used if this value is not provided. |
type |
type | How this field should be treated, either internal, context or localizable (see below). Required |
data |
data type | The type of data this field contains, two types are currently supported: string and html. Required |
value |
dynamic | Value of this field. Required for internal, context and localizable, has to be nullfor creatable fields. |
originalValue |
dynamic | Original value of this field. Only readable |
intermediateValue |
dynamic | Intermediate value of this field. Used for things such as machine translation that can deliver unfinished values for early use. Only readable |
Field types
More details of how to use the field types can be found in the examples found further down on this page.
| Name | Description |
|---|---|
internal |
Used for storing data relevant to the submitter but that does not affect the localization and creation of content. |
context |
Contextual information to help writers with localization and content creation. |
localizable |
Used for fields where the value should be localized into another language. |
creatable |
Used for fields where content should be created based on context and hints. |
Data types
| Name | Description |
|---|---|
string |
String of text - no formatting and will not be encoded. JSON data is expected to be a string. |
html |
HTML formatted text, needs to be a valid HTML fragment and will be returned HTML encoded. JSON data is expected to be a string. |
Content request fields with HTML value must not contain HTML comments within other content. If HTML comments are provided they must be the first or/and last elements in that field. Mixing up HTML comments with script- and style tags is supported as long as all these elements are first or/and last.
Hints
Hints are valuable tools for enhancing the quality of your content creation process. You can apply various types of hints to your fields,
covering a spectrum from soft guidance, such as defining a target word count, to more stringent requirements, like enforcing a maximum
length to ensure compliance with database limitations. These hints can be tailored to each specific field you provide.
Hints are specified via an array on the field named hints. Example:
{
"id": "title",
"type": "localizable",
"data": "string",
"value": "Products",
"hints": [
{
"type": "length",
"max": 400
}
]
}
Length limit
Limit the length of the text in a field in characters.
Type: length
Use: Works for localizable and creatable fields.
| Argument | Description |
|---|---|
around |
Optional length of the text, used as an indicator of a desired length, but the finished text can be shorter than this text. |
max |
Optional maximum length of the returned text. The finished text will never be longer than this. |
Word count
Set a target on the number of words a text should have.
Type: word-count
Use: Only with field type creatable.
| Argument | Description |
|---|---|
around |
Required for creatable. Number of words that the created text should aim for. Used as an indicator on how many words the text should have, but a returned text is allowed to have less words. |
Free text
Ties some free text information to a field, similar to context but scoped to a single field.
Type: free-text
Use: Works for localizable and creatable fields.
| Argument | Description |
|---|---|
text |
The text that should be associated with this field. |
Examples of fields
Internal
A field categorized as internal serves as a non-visible element during the localization and content creation processes.
This field type is primarily designed for maintaining internal IDs within the integrating system. Its purpose is to preserve
and track crucial information from the source system. By doing so, it ensures data integrity and consistency, providing a
reliable way to link back to the original data and maintain a coherent record throughout the integration process.
{
"id": "product-id",
"type": "internal",
"data": "string",
"value": "145007"
}
Context
Fields classified as 'context' are intended to offer additional background information and context during the localization and content creation process. For instance, context may encompass descriptive text or a URL leading to a product description with accompanying images. Context fields can be used as criterias when querying.
{
"id": "product-type",
"type": "context",
"data": "string",
"value": "Coffee Brewer"
}
Localizable
Localizable fields are the main type of fields when content is meant to be translated or localized from one language to another.
The value property determines the source content.
{
"id": "product-listing-text",
"type": "localizable",
"data": "html",
"value": "Coffee Brewer with integrated timer & automatic shut down."
}
When a localizable field is processed and returned from the API the source value sent in the request is moved to a property
called originalValue and the translated/localized value is held in the value property.
{
"id": "product-listing-text",
"type": "localizable",
"data": "html",
"value": "Kaffebryggare med integrerad timer & automatisk avstängning.",
"originalValue": "Coffee Brewer with integrated timer & automatic shut down."
}
Creatable
As previously mentioned, hints serve as valuable instructions, particularly when generating new content. Below is an example on a such request, asking for a summary of a product description containing approximately 15 words.
{
"id": "short description",
"type": "creatable",
"data": "html",
"hints": [
{
"type": "free-text",
"text": "Summarize product description for Coffee Brewer A"
},
{
"type": "word-count",
"around": 15
}
]
}
When such a field is returned from the API (after the content is created) it may look as the example below.
{
"id": "short description",
"type": "creatable",
"data": "html",
"value": "Coffee Brewer with integrated timer & automatic shut off and a “time to clean” indicator light.",
"hints": [
{
"type": "free-text",
"text": "Summarize product description for Coffee Brewer A"
},
{
"type": "word-count",
"around": 15
}
]
}