Skip to main content

Translate Handbook

Translate a handbook's content from English to Spanish using AI. The translated content is saved to the handbook's Spanish content field (contentEs) and can be retrieved via the getHandbook query.

Mutation​

mutation TranslateHandbook($handbookId: Int!, $handbookType: String) {
  translateHandbook(handbookId: $handbookId, handbookType: $handbookType) {
    success
    handbookId
    message
  }
}

Parameters​

ParameterTypeRequiredDescription
handbookIdInt!YesThe handbook ID to translate
handbookTypeStringNoHandbook type. Defaults to "comprehensive"

Response​

The mutation returns immediately after accepting the translation request. Translation runs in the background.

{
  "data": {
    "translateHandbook": {
      "success": true,
      "handbookId": 123,
      "message": "Translation started. This may take 1-2 minutes. Use the getHandbook query to retrieve the Spanish content (contentEs) once complete."
    }
  }
}

Examples​

Basic Usage​

mutation {
  translateHandbook(handbookId: 123) {
    success
    handbookId
    message
  }
}

With Variables​

mutation Translate($handbookId: Int!) {
  translateHandbook(handbookId: $handbookId) {
    success
    handbookId
    message
  }
}

Variables:

{
  "handbookId": 123
}

Poll for Spanish Content​

After the mutation returns, poll getHandbook to check when translation is complete. The contentEs field will be null until translation finishes.

query {
  getHandbook(handbookId: 123) {
    handbookId
    content
    contentEs
  }
}

Error Responses​

Handbook Not Found​

{
  "errors": [
    {
      "message": "Handbook not found"
    }
  ]
}

Access Denied​

{
  "errors": [
    {
      "message": "Handbook not found or access denied"
    }
  ]
}

Subscription Required​

{
  "errors": [
    {
      "message": "This operation requires an active subscription. ONE_TIME or unsubscribed handbooks are not supported."
    }
  ]
}

No Content to Translate​

{
  "errors": [
    {
      "message": "No handbook content found to translate"
    }
  ]
}

Translation Service Not Configured​

{
  "errors": [
    {
      "message": "Translation service not configured"
    }
  ]
}

Notes​

  • Requires reseller API key authentication
  • Requires an active subscription (SUBSCRIPTION status) — ONE_TIME or unsubscribed handbooks are not supported
  • The handbook must belong to a customer of the authenticated reseller
  • Translation runs asynchronously — the mutation returns immediately and translation runs in the background
  • Translation typically takes 1-2 minutes for large handbooks
  • Poll the getHandbook query and check the contentEs field to know when translation is complete
  • Translation success or failure is logged to reseller_builder_log
  • Translates the current English content of the handbook to Spanish
  • Uses AI (Google Gemini) for translation — preserves all HTML structure, tags, and attributes
  • Large documents are automatically split into sections and translated in parallel for speed
  • Company names and proper nouns are preserved (not translated)
  • Uses formal Spanish (usted) appropriate for business documents
  • The translated content is saved to the contentEs field and replaces any existing Spanish content