Translations & Localization

Translate your store content into 15 languages using the Admin Translations API with optional AI-powered auto-translate.

Overview

Cartly uses two complementary translation layers:

DB Entity Translations — per-entity, per-locale strings stored in the translation table. Covers products, collections, pages, articles, menus, and metafields.
Static Locale Files — storefront UI strings compiled into locales/*.json and rendered via the {{ ' key' | t }} Liquid filter. Managed per-theme.

Entity Translations API

Use the Translations API to read and write translated content for any entity. All endpoints require admin JWT authentication.

Method	Path	Description
GET	`/admin/translations/:type/:entityId`	Get all locales for an entity
GET	`/admin/translations/:type/:entityId/:locale`	Get translations for one locale
PUT	`/admin/translations/:type/:entityId/:locale`	Save specific field translations
DELETE	`/admin/translations/:type/:entityId/:locale`	Delete a locale translation
POST	`/admin/translations/auto-translate`	AI auto-translate one field for one entity+locale

Supported Entity Types

product, variant, collection, page, article, menu, metafield

GET /admin/translations/product/:entityId/:locale

bash

curl -X GET "https://cartly.pro/admin/translations/product/PRODUCT_ID/de" \
  -H "Authorization: Bearer ADMIN_JWT"

# Response
# {
#   "locale": "de",
#   "fields": {
#     "title": "Klassisches T-Shirt",
#     "description": "Ein bequemes Baumwoll-T-Shirt"
#   }
# }

PUT /admin/translations/:type/:entityId/:locale

bash

curl -X PUT "https://cartly.pro/admin/translations/product/PRODUCT_ID/de" \
  -H "Authorization: Bearer ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Klassisches T-Shirt",
    "description": "Ein bequemes Baumwoll-T-Shirt in mehreren Farben"
  }'

AI Auto-Translate

The POST /admin/translations/auto-translate endpoint uses Gemini to translate or generate content for a single field.

Request Body

Field	Type	Description
`entity_type`	string	e.g. `product`, `collection`
`entity_id`	string (UUID)	Target entity ID
`locale`	string	Target locale (e.g. `de`, `fr`)
`field`	string	Field name: `title`, `description`, `seo_title`, `seo_description`, `content`
`mode`	string	`translate` (preserve meaning) or `generate` (SEO-optimized)

Billing Limits

AI translation is metered per plan. Exceeding limits returns:

plan_required — AI features require a paid plan
chars_exceeded — monthly character quota reached; upgrade to continue

Audit Logging

Every call to auto-translate is recorded in ai_audit_logs with entity type, entity ID, locale, field, token count, and latency.

POST /admin/translations/auto-translate

bash

curl -X POST "https://cartly.pro/admin/translations/auto-translate" \
  -H "Authorization: Bearer ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "product",
    "entity_id": "PRODUCT_UUID",
    "locale": "de",
    "field": "title",
    "mode": "translate"
  }'

# Response
# { "result": "Klassisches T-Shirt" }

Integration Workflow

Fetch existing product: GET /admin/products/:id
Translate a field: POST /admin/translations/auto-translate with mode: translate
Save the result: PUT /admin/translations/product/:id/:locale with translated field
Storefront automatically serves translated content when the Accept-Language or market locale matches

Supported Locales

Built-in storefront locales: en, ru, de, fr, es, uk. Additional AI-translation targets: zh, ja, ko, ar, pt, it, nl, pl, tr.