Translations

Language Support

The API supports translations for any language code. You can use any ISO language code (e.g., 'de' for German, 'ja' for Japanese, etc.) when creating translations.

The CX (Customer Experience) we build can support translations for any language code, providing flexibility for global applications.

The following languages are specifically supported within the EON Platform:

Translation Data Structure

Translations are stored per language in a nested format. Example:

{
    "translations": {
        "fr": {
            "name": "Nom du produit",
            "description": "Description du produit en français",
            "brand": "Marque",
            "custom_data": {
                "custom_field": "Valeur personnalisée"
            }
        },
        "es": {
            "name": "Nombre del producto",
            "description": "Descripción del producto en español",
            "brand": "Marca",
            "custom_data": {
                "custom_field": "Valor personalizado"
            }
        }
    }
}

Translatable Fields

The system allows translation of most standard Product fields, including:

• Basic fields: name, description, brand, etc.
• Custom data fields
• Category fields
• Product details and specifications

Identifier fields cannot be translated (id, gtin, internal_id)

API Usage

Retrieving Translations

You can access translations in two ways:

1. Request a specific language: Directly get a product with fields translated to a specific language
   GET /api/v2/products/{id}/?include=translations
2. Include the translations field: Retrieve all available translations for a product
   GET /api/v2/products/{id}/?lang=fr

When using the `lang` parameter, the API will return the product with all translatable fields replaced with their translations in the requested language. If a specific field doesn't have a translation, the original value is returned.
‍

Creating or Updating Translations

To add or update translations for a product:

PATCH /api/v2/products/{id}/?merge=true
{
  "translations": {
    "fr": {
      "name": "Nouveau nom",
      "description": "Nouvelle description"
    }
  }
}

This will update only the specified fields in the French translation, leaving other translations and fields unchanged. The `merge=true` parameter is important to ensure you don't overwrite existing translations.
‍

Non-translations field can be included alongside the translations field:
‍

PATCH /api/v2/products/{id}/?merge=true
{
  "name": "New name",
  "description": "New description",
  "custom_data": {
    "custom_field_1": "English value"
  },
  "translations": {
    "fr": {
      "name": "Nouveau nom",
      "description": "Nouvelle description",
      "custom_data": {
        "custom_field_1": "Valeur française"
      }
    }
  }
}

Fields outside the translations field are typically considered the English values of the fields.
‍

Using Deep Merge for Updates

The API supports deep merging of nested objects when updating translations using the `merge=true` query parameter:

PATCH /api/v2/products/{id}/?merge=true
{
  "translations": {
    "fr": {
      "custom_data": {
        "new_field": "Nouvelle valeur"
      }
    }
  }
}

With `merge=true`, this update will:

• Keep all existing French translations
• Keep all existing custom_data fields for French
• Add the new_field to custom_data without removing existing fields

This is particularly useful for updating deeply nested translation fields without having to provide the complete object structure.
‍

Advanced Export with Translations

Translations can be used with the advanced export feature, but this functionality is currently only available for Products (not Items or other entities). You can include translated fields in your exports by using the schema-based export endpoint.

To export product data with translations:

POST /api/v2/products/export/?lang=fr&q=search_term&brand=brand_name
{
  "fields": ["name", "description", "brand", "custom_data.field1"]
}

The export will include the translated values for the requested fields in the specified language. If a translation doesn't exist for a particular field, the original value will be used.

Note that all filters should be provided as query parameters in the URL.

Permissions

You’ll need the following permissions to interact with translations:

• read_product_translations: Required to access translations data
• update_product_translations: Required to create or update translations

These permissions must be assigned to API users or devices that need to work with translations.

Best Practices

1. Maintain Complete Translations: Ensure all required fields are translated for each supported language
2. Validate Translations: Use the EON API to validate translations against the schema
3. Use Language Codes Consistently: Follow ISO language code standards (e.g., 'fr' for French)
4. Update Translations Atomically: When updating translations, include only the fields you're changing
5. Check Permissions: Ensure your API users have the required translation permissions
6. Use Deep Merge: When updating nested fields, use the merge=true parameter to avoid overwriting existing data

Integration Requirements

To integrate with the EON translation system, you need:

1. API credentials with the appropriate translation permissions
2. Implementation of API calls using the `lang` parameter or `translations` field
3. Proper handling of translation updates through the API

Example API Requests

Get a product with translations included:
GET /api/v2/products/12345/?include=translations
‍

Get a product directly translated to Spanish:
GET /api/v2/products/12345/?lang=es
‍

Update French translations for specific fields (with merge):

PATCH /api/v2/products/12345/?merge=true
Content-Type: application/json

{
  "translations": {
    "fr": {
      "name": "Nom du produit en français",
      "description": "Description détaillée en français",
      "custom_data": {
        "material_info": "Information sur le matériel"
      }
    }
  }
}