Localized String

The Propeller REST API uses LocalizedString and LocalizedStringArray data types to handle multi-language content throughout the platform. These types allow you to store and retrieve content in multiple languages for various entities like products, categories, surcharges, and more.

Overview

Localized content is essential for international ecommerce platforms. The Propeller API provides two main data types for handling multi-language content:

• LocalizedString: For single text values in multiple languages
• LocalizedStringArray: For arrays of text values in multiple languages

LocalizedString

A LocalizedString is used for fields that contain a single translatable value across multiple languages.

Structure

{
  "language": "EN",
  "value": "Product Name"
}

Properties

Property	Type	Required	Description	Example
language	string	Yes	2-character language code per ISO 639-1	"EN", "NL", "DE"
value	string	Yes	The translated text content	"Product Name"

Usage in Arrays

LocalizedString is typically used in arrays to represent content in multiple languages:

[
  {
    "language": "EN",
    "value": "Product Name"
  },
  {
    "language": "NL", 
    "value": "Productnaam"
  },
  {
    "language": "DE",
    "value": "Produktname"
  }
]

LocalizedStringArray

A LocalizedStringArray is used for fields that contain multiple text values in multiple languages, such as tags, keywords, or lists.

Structure

{
  "language": "EN",
  "values": ["Tag1", "Tag2", "Tag3"]
}

Properties

Property	Type	Required	Description	Example
language	string	Yes	2-character language code per ISO 639-1	"EN", "NL", "DE"
values	string[]	Yes	Array of translated text values	["Tag1", "Tag2", "Tag3"]

Usage in Arrays

LocalizedStringArray is typically used in arrays to represent multiple values in multiple languages:

[
  {
    "language": "EN",
    "values": ["Electronics", "Gadgets", "Technology"]
  },
  {
    "language": "NL",
    "values": ["Elektronica", "Gadgets", "Technologie"]
  },
  {
    "language": "DE", 
    "values": ["Elektronik", "Gadgets", "Technologie"]
  }
]

Common Use Cases

Product Information

Products use LocalizedString for names, descriptions, and other translatable content:

{
  "names": [
    {"language": "EN", "value": "Garmin Edge 1030"},
    {"language": "NL", "value": "Garmin Edge 1030"},
    {"language": "DE", "value": "Garmin Edge 1030"}
  ],
  "descriptions": [
    {"language": "EN", "value": "High-end cycling computer with advanced features"},
    {"language": "NL", "value": "High-end fietscomputer met geavanceerde functies"},
    {"language": "DE", "value": "High-End-Fahrradcomputer mit erweiterten Funktionen"}
  ],
  "keywords": [
    {"language": "EN", "values": ["cycling", "computer", "GPS"]},
    {"language": "NL", "values": ["fietsen", "computer", "GPS"]},
    {"language": "DE", "values": ["Radfahren", "Computer", "GPS"]}
  ]
}

Attributes

Attributes use LocalizedStringArray for text values that can have multiple entries per language:

{
  "textValues": [
    {
      "language": "EN",
      "values": ["Red", "Blue", "Green"]
    },
    {
      "language": "NL", 
      "values": ["Rood", "Blauw", "Groen"]
    },
    {
      "language": "DE",
      "values": ["Rot", "Blau", "Grün"]
    }
  ]
}

Language Codes

The API uses standard 2-character language codes as defined by ISO 639-1:

Language	Code	Language	Code
English	EN	Dutch	NL
German	DE	French	FR
Spanish	ES	Italian	IT
Portuguese	PT	Swedish	SV
Norwegian	NO	Danish	DA
Finnish	FI	Polish	PL
Czech	CS	Hungarian	HU
Slovak	SK	Slovenian	SL
Croatian	HR	Serbian	SR
Bulgarian	BG	Romanian	RO
Greek	EL	Turkish	TR
Russian	RU	Ukrainian	UK
Japanese	JA	Korean	KO
Chinese (Simplified)	ZH	Chinese (Traditional)	ZH-TW
Arabic	AR	Hebrew	HE
Thai	TH	Vietnamese	VI

important

The Language Codes are always UPPERCASE

API Integration Examples

Creating a Product with Localized Content

POST /v2/products
Content-Type: application/json

{
  "names": [
    {"language": "EN", "value": "Garmin Edge 1030"},
    {"language": "NL", "value": "Garmin Edge 1030"},
    {"language": "DE", "value": "Garmin Edge 1030"}
  ],
  "descriptions": [
    {"language": "EN", "value": "High-end cycling computer with advanced features"},
    {"language": "NL", "value": "High-end fietscomputer met geavanceerde functies"},
    {"language": "DE", "value": "High-End-Fahrradcomputer mit erweiterten Funktionen"}
  ],
  "keywords": [
    {"language": "EN", "values": ["cycling", "computer", "GPS"]},
    {"language": "NL", "values": ["fietsen", "computer", "GPS"]},
    {"language": "DE", "values": ["Radfahren", "Computer", "GPS"]}
  ]
}

Retrieving Localized Content

# Get product with default language only
GET /v2/products/123?language=EN

# Get product with all translations
GET /v2/products/123?expands=translation

Error Handling

Common Validation Errors

{
  "error": {
    "code": 10007,
    "status": 400,
    "type": "ValidationError",
    "messages": [
      "Invalid language code: 'XX'",
      "Missing required field 'value' for language 'EN'",
      "Duplicate language code 'EN' found"
    ]
  }
}

Handling Missing Translations

When a translation is not available, the API will return the default language or the first available translation. Always implement fallback logic in your application.

LocalizedString and LocalizedStringArray provide a robust foundation for multi-language content management in the Propeller platform. Use these types consistently across all translatable content to ensure a seamless international user experience.