Translations

Translation management for storefront text and multi-language support

Get system default translations

get

https://dev-api.joy.sohttps://api.joy.so

/rest_api/v2/translations/defaults

Returns system default translations only (no merchant overrides). Use this to compare against GET /translations and identify which values are merchant customizations vs system defaults.

Important: Also use this endpoint to look up the correct translation key before calling PUT. Many keys have internal prefixes (e.g., [[WidgetV2]], [[Checkout]]) that differ from the displayed UI text. Search by value (not key) in the response to find the exact key to use in PUT requests.

Authorizations

JoyAuth & JoySecretAuth

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Responses

200

System default translations for all supported locales

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

get/rest_api/v2/translations/defaults

HTTPcURLJavaScriptPython

GET /rest_api/v2/translations/defaults HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*

200

System default translations for all supported locales

{
  "success": true,
  "data": {
    "ANY_ADDITIONAL_PROPERTY": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Get all translations

get

https://dev-api.joy.sohttps://api.joy.so

/rest_api/v2/translations

Returns translation config and text for ALL languages (primary + additional), merged with system defaults. Each language contains ~300+ translation key-value pairs.

Response includes config fields (primaryLanguage, detectMethod, additionalLanguages, embedContent) and dynamic language objects (en, fr, de, etc.) with translation key-value pairs.

Authorizations

JoyAuth & JoySecretAuth

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Responses

200

Full translation config and text

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

get/rest_api/v2/translations

HTTPcURLJavaScriptPython

GET /rest_api/v2/translations HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*

200

Full translation config and text

{
  "success": true,
  "data": {
    "primaryLanguage": "en",
    "detectMethod": "browserLanguage",
    "additionalLanguages": [
      {
        "code": "fr",
        "active": true
      }
    ],
    "embedContent": [
      "en",
      "fr"
    ],
    "en": {
      "Join Program": "Join Program",
      "Redeem": "Redeem",
      "Ways to earn": "Ways to earn"
    },
    "fr": {
      "Join Program": "Rejoindre le programme",
      "Redeem": "Échanger",
      "Ways to earn": "Façons de gagner"
    }
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Update translations

put

https://dev-api.joy.sohttps://api.joy.so

/rest_api/v2/translations

Updates translation config and text. Send the full translation object from the GET response with modifications applied (not partial updates).

⚠️ Key Lookup Warning: Translation keys are NOT always the same as the displayed UI text. Many keys have internal prefixes such as [[WidgetV2]], [[Checkout]], [[POS]], etc.

Example:

• UI text: Ways to earn

• Actual key: [[WidgetV2]]Ways to earn

Before calling PUT to update a specific text:

1. ALWAYS call GET /translations/defaults first

2. Search by VALUE (not key) to find the correct key — filter entries where value matches the target text

3. Use the exact key found in step 2 for the PUT request

Sending a PUT with a non-existent key will return success: true but will have no visible effect on the storefront.

Workflow: GET /translations/defaults → find correct key by value → GET /translations → modify keys → PUT /translations with entire object.

Behavior:

1. Diffs request vs system defaults — only stores overrides in Firestore

2. If primaryLanguage or its content changed — auto-translates ALL additional languages via Google Translate API

3. If embedContent changed — triggers background jobs for FAQs and exclusive products

4. Publishes metafield sync to Shopify

Idempotent: GET → PUT unchanged = no side effects (diff produces empty result).

CRITICAL — PUT REPLACES, does NOT merge: Sending only a subset of keys will DELETE all other existing merchant customizations. You MUST send the complete object from GET with your modifications applied.

Data loss example:

• Existing customs: {en: {"A": "custom A", "B": "custom B"}}

• PUT with: {en: {"C": "custom C"}} (partial)

• Result: {en: {"C": "custom C"}} — A and B are permanently lost

Correct workflow:

1. GET /translations — get current full state (all keys)

2. GET /translations/defaults — get system defaults

3. Find the correct key by searching defaults by VALUE

4. Modify the key in the full GET response

5. PUT /translations — send the entire modified object back

Authorizations

JoyAuth & JoySecretAuth

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Body

application/json

Full translation object containing config and text for all languages. Language keys (en, fr, de...) are dynamic objects with translation key-value pairs. Mirrors the internal admin translation system.

primaryLanguagestringOptional

Primary language code

Example: en

detectMethodstring · enumOptional

How to detect customer language:

• customerIp: By IP geolocation
• browserLanguage: By browser language setting
• optionalStorefrontLanguage: Use Shopify storefront language

Example: browserLanguagePossible values:

embedContentstring[]Optional

Languages for embedded content (FAQs, exclusive products)

Example: ["en","fr"]

Responses

200

Save succeeded

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

500

Firestore save failed (e.g., undefined values in data)

application/json

put/rest_api/v2/translations

HTTPcURLJavaScriptPython

PUT /rest_api/v2/translations HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 57

{
  "primaryLanguage": "en",
  "detectMethod": "browserLanguage"
}

Change language detection methodUpdate translation text (MUST include ALL keys from GET, not just changed ones)

{
  "success": true,
  "data": {
    "updated": true
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Add a new language

post

https://dev-api.joy.sohttps://api.joy.so

/rest_api/v2/translations/languages

Adds a new language and auto-translates all text (~300+ keys) from the primary language using Google Translate API. Also auto-translates program titles and milestone descriptions.

Returns the full translation object with the new language included.

Authorizations

JoyAuth & JoySecretAuth

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Body

application/json

primaryLanguagestringRequired

Source language code to translate from

Example: en

additionalLanguagestringRequired

Target language code to add

Example: fr

Responses

201

Language added with auto-translated text

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

400

Invalid or unsupported locale

application/json

post/rest_api/v2/translations/languages

HTTPcURLJavaScriptPython

POST /rest_api/v2/translations/languages HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 50

{
  "primaryLanguage": "en",
  "additionalLanguage": "fr"
}

{
  "success": true,
  "data": {
    "primaryLanguage": "en",
    "detectMethod": "browserLanguage",
    "additionalLanguages": [
      {
        "code": "fr",
        "active": true
      }
    ],
    "embedContent": [
      "en",
      "fr"
    ],
    "en": {
      "Join Program": "Join Program",
      "Redeem": "Redeem",
      "Ways to earn": "Ways to earn"
    },
    "fr": {
      "Join Program": "Rejoindre le programme",
      "Redeem": "Échanger",
      "Ways to earn": "Façons de gagner"
    }
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Remove a language

delete

https://dev-api.joy.sohttps://api.joy.so

/rest_api/v2/translations/languages/{locale}

Removes a language. Clears all translation data for that locale and removes it from the additionalLanguages array. Publishes metafield sync after removal.

Authorizations

JoyAuth & JoySecretAuth

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Path parameters

localestringRequired

Language code to remove

Example: fr

Responses

200

Language removed

application/json

successbooleanOptionalExample: true

404

No translation document found for shop

application/json

delete/rest_api/v2/translations/languages/{locale}

HTTPcURLJavaScriptPython

DELETE /rest_api/v2/translations/languages/{locale} HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*

{
  "success": true
}

Update FAQ translations

put

https://dev-api.joy.sohttps://api.joy.so

/rest_api/v2/translations/faqs

Updates FAQ translations separately from main translations. Each language has an array of FAQ items (title, content, orderBy). Triggers a background job to process FAQ translation updates and sync to Shopify metafields.

Authorizations

JoyAuth & JoySecretAuth

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Body

application/json

Responses

200

FAQ translations updated

application/json

successbooleanOptionalExample: true

400

Missing translateFaqs field

application/json

put/rest_api/v2/translations/faqs

HTTPcURLJavaScriptPython

PUT /rest_api/v2/translations/faqs HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 213

{
  "translateFaqs": {
    "en": [
      {
        "title": "How does it work?",
        "content": "Earn points on every purchase...",
        "orderBy": 0
      }
    ],
    "fr": [
      {
        "title": "Comment ça marche?",
        "content": "Gagnez des points à chaque achat...",
        "orderBy": 0
      }
    ]
  }
}

{
  "success": true
}