API Integration with post translations

The Plate API provides comprehensive functionality for managing post translations across different languages. This guide covers how to create, link, unlink, and manage post translations.

Concept

Post translations link content across different languages. When creating theme_files, these translations can be accessed in liquid code for language navigation. For more details, see the liquid guide.

Example

Consider a contact page available in multiple languages:

/contact
/en/contact
/de/kontakt

These posts contain the same content in different languages. To find the translation of a post in a different language, look up a post translations attribute.

A post can only have one translation per language. For example: you cannot create an extra translation for English or German in the above example within this group.

Creating Post Translations

Create a new Post

Create a post directly in a specific language using the site translation endpoint.

API Endpoint details: Create a new post

curl -X POST "https://www.startwithplate.com/api/v2/site_translations/123/posts" \
  -H "Content-Type: application/json" \
  -H "Date: $(date -u +'%a, %d %b %Y %H:%M:%S GMT')" \
  -H "Authorization: hmac YOUR_PUBLIC_KEY:YOUR_SIGNATURE" \
  -d '{
    "data": {
      "title": "My Post Title",
      "content_type_id": 1,
      "language": "en",
      "content_field_name": {
        "content": "This is the post content"
      }
    }
  }'

Go to Authentication and Authorization to calculate your signature

Linking an Existing Post

To link an existing post as a translation of another post, use the translation_of_id parameter when updating.

API Endpoint details: Update Post

curl -X PUT "https://www.startwithplate.com/api/v2/posts/456" \
  -H "Content-Type: application/json" \
  -H "Date: $(date -u +'%a, %d %b %Y %H:%M:%S GMT')" \
  -H "Authorization: hmac YOUR_PUBLIC_KEY:YOUR_SIGNATURE" \
  -d '{
    "data": {
      "translation_of_id": 123
    }
  }'

What happens:

Post 456 becomes a translation of Post 123
If Post 123 was previously linked to another translation, you’ll see an error asking you to unlink it first.

Disconnecting Post Translations

Method 1: Update to translation_of_id to 0

To disconnect a post from its translation group, update the post with translation_of_id: 0:

curl -X PUT "https://www.startwithplate.com/api/v2/posts/456" \
  -H "Content-Type: application/json" \
  -H "Date: $(date -u +'%a, %d %b %Y %H:%M:%S GMT')" \
  -H "Authorization: hmac YOUR_PUBLIC_KEY:YOUR_SIGNATURE" \
  -d '{
    "data": {
      "translation_of_id": 0
    }
  }'

What happens: The post becomes a standalone post and doesn’t have any translated versions

Method 2: Replace translation link

When linking a post to a new translation, the old translation of post 456 is automatically unlinked:

# This will unlink post 456 from its current translation and link it to post 789
curl -X PUT "https://www.startwithplate.com/api/v2/posts/456" \
  -H "Content-Type: application/json" \
  -H "Date: $(date -u +'%a, %d %b %Y %H:%M:%S GMT')" \
  -H "Authorization: hmac YOUR_PUBLIC_KEY:YOUR_SIGNATURE" \
  -d '{
    "data": {
      "translation_of_id": 789
    }
  }'

Limitations and Constraints

Language requirements

Posts must be in different languages within the same site
Only one post per language per translation
Each post can only be a translated version of another post.

Connected posts: Posts that are connected as targets to other sites cannot be updated
Index posts: Index posts (main page posts) have special protection and limitations

System behavior

Circular prevention: The system prevents circular translation relationships
Group cleanup: When the last post is removed from a translation group, the group is automatically cleaned up
Duplication placeholders: When duplicating a post to another language, a placeholder is created immediately, and the actual duplication happens asynchronously

Filtering

Webhooks

How to create and manage webhooks in Plate Multisite