# How to Build a Custom Translation API Integration | Vitra.ai > When no connector fits, the API is the answer. Four decisions determine whether the integration is maintainable or a permanent liability as well. **Canonical URL**: https://www.vitra.ai/general/custom-translation-api-integration **Source**: This is the Markdown rendering of https://www.vitra.ai/general/custom-translation-api-integration, generated at build time from that page. --- 4 min read # How to Build a Custom Translation API Integration When no connector fits, the API is the answer. Four decisions determine whether the integration is maintainable or a permanent liability as well. [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Senior Product Manager , Vitra.ai Updated Aug 17, 2026 ![How to Build a Custom Translation API Integration](https://www.vitra.ai/static/images/blog/custom-translation-api-integration.jpg) Table of contents [When a custom integration is the right call](#when-a-custom-integration-is-the-right-call) [Decision one: what triggers translation](#decision-one-what-triggers-translation) [Decision two: chunking](#decision-two-chunking) [Decision three: synchronous or asynchronous](#decision-three-synchronous-or-asynchronous) [Decision four: change detection](#decision-four-change-detection) [The things people forget](#the-things-people-forget) [Beyond REST](#beyond-rest) [Logging and observability](#logging-and-observability) [Where to start](#where-to-start) [FAQ](#faq) Contributors [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Senior Product Manager Subscribe to our newsletter Subscribe > **Quick answer —** A custom integration means calling the translation API directly from your own system. The four decisions that matter are what triggers translation, how content is chunked, how results come back, and what happens when the source changes. ## When a custom integration is the right call An internal system with no connector. A proprietary CMS. A workflow that has to run inside an existing approval process. A content type nobody else has. If a connector exists, use it — a custom integration is code you own forever. If one does not, the API is straightforward and the decisions below are the ones that determine whether you regret it. ## Decision one: what triggers translation Event-driven, on the publish or update event, is almost always right. A nightly batch means content is stale for up to a day and a manual trigger means content is stale until somebody remembers. The event-driven version is also what prevents the classic failure: source content edited, translations left behind, nobody aware. ## Decision two: chunking Send a whole document and you get context, consistency and a slower response. Send a string at a time and you get speed and translations that cannot see the sentence around them. Chunk at a natural boundary — a section, a field, a record. Never split a sentence across requests, and keep related fields together so a title and its description are translated with knowledge of each other. ## Decision three: synchronous or asynchronous Anything user-facing and short can be synchronous. Anything at volume should be asynchronous with a callback, because a request that takes ninety seconds will hit a timeout somewhere in your stack that you do not control. Build for the asynchronous case even if you start synchronous. Retrofitting it means changing the calling code. ## Decision four: change detection Store a hash of the source alongside the translation. When the source changes, the hash differs and the translation is stale. Without this, you have no way to know what needs re-translating, and the system degrades into a full re-translation on every run, which is expensive, or no re-translation at all, which is worse. ## The things people forget Rate limits and backoff. Idempotency, so a retry does not duplicate work. A glossary passed with each request rather than hoped for. [translation memory](https://www.vitra.ai/features/translation-memory) so repeated content is not paid for twice. [quality control](https://www.vitra.ai/features/quality-control) so there is a record of what was reviewed. And error handling that fails visibly. A silent failure returning source text looks like success and ships English into a translated system. ## Beyond REST MCP, SDKs, CLI access and connectors through n8n, Make or Zapier cover a lot of cases that look custom at first glance. [agentic workflows](https://www.vitra.ai/features/agentic-workflows) is worth checking before writing code, because an orchestrated workflow is usually less to maintain than an integration. Options are on the [custom integration](https://www.vitra.ai/integration/custom-integration) page. ## Logging and observability Log the request, the response status and the content hash for every call. When somebody asks why a page is in the wrong language six weeks later, that log is the only way to answer. Without it, debugging a translation integration means re-running it and hoping the failure reproduces, which for an event-driven system it usually will not. ## Where to start Write the change-detection logic first. Everything else is a call; that is the part that decides whether the integration stays correct. ## FAQ **When should I build a custom translation integration?** When no connector fits — an internal system, a proprietary CMS, a content type nobody else has, or a workflow that must run inside an existing approval process. If a connector exists, use it. **What should trigger translation?** The publish or update event. A nightly batch leaves content stale for up to a day and a manual trigger leaves it stale until somebody remembers, which is how translations fall permanently behind their source. **How should content be chunked for the API?** At a natural boundary such as a section, field or record, never splitting a sentence across requests. Keep related fields together so a title and its description are translated with knowledge of each other. **How do I know what needs re-translating?** Store a hash of the source alongside the translation. When the hash differs the translation is stale. Without it the system either re-translates everything each run or never re-translates at all. Our blog ## Lastest blog posts Tool and strategies modern teams need to help their companies grow. Automotive [Automotive Brochure Localization by Market](https://www.vitra.ai/automotive/automotive-brochure-localization) A car brochure is a spec grid, a legal footer and a photo library, all market-specific. What actually has to change, and why the layout decides the schedule. [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Aug 18, 2026 Automotive [Automotive Campaign Localization Across Markets](https://www.vitra.ai/automotive/automotive-campaign-localization) Campaigns run through national companies and dealer networks, so one master becomes hundreds of files. Where the offer text and the disclaimers actually break. [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Aug 18, 2026 Automotive [Car Service Manual Translation for Technicians](https://www.vitra.ai/automotive/automotive-service-manual-translation) A workshop manual is read mid-repair by someone with the car on a lift. What that demands of procedures, torque figures and fault codes, in every language. [Samhitha J Bhatt](https://www.vitra.ai/author/samhitha) Aug 18, 2026 [View all posts](https://www.vitra.ai/blog/page/1) --- ## Structured data ```json { "@context": "https://schema.org", "@type": "Article", "mainEntityOfPage": { "@type": "WebPage", "@id": "https://www.vitra.ai/general/custom-translation-api-integration" }, "headline": "How to Build a Custom Translation API Integration", "image": [ { "@type": "ImageObject", "url": "https://www.vitra.ai/static/images/blog/custom-translation-api-integration.jpg" } ], "datePublished": "2026-08-17T00:00:00.000Z", "dateModified": "2026-08-17T00:00:00.000Z", "author": [ { "@type": "Person", "name": "Samhitha J Bhatt" } ], "publisher": { "@type": "Organization", "name": "Vitra.ai", "logo": { "@type": "ImageObject", "url": "https://www.vitra.ai/static/images/vitra-v-logo.png" } }, "description": "When no connector fits, the API is the answer. Four decisions determine whether the integration is maintainable or a permanent liability as well." } ``` ```json { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://www.vitra.ai" }, { "@type": "ListItem", "position": 2, "name": "General", "item": "https://www.vitra.ai/general" }, { "@type": "ListItem", "position": 3, "name": "How to Build a Custom Translation API Integration", "item": "https://www.vitra.ai/general/custom-translation-api-integration" } ] } ``` ```json { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "When should I build a custom translation integration?", "acceptedAnswer": { "@type": "Answer", "text": "When no connector fits — an internal system, a proprietary CMS, a content type nobody else has, or a workflow that must run inside an existing approval process. If a connector exists, use it." } }, { "@type": "Question", "name": "What should trigger translation?", "acceptedAnswer": { "@type": "Answer", "text": "The publish or update event. A nightly batch leaves content stale for up to a day and a manual trigger leaves it stale until somebody remembers, which is how translations fall permanently behind their source." } }, { "@type": "Question", "name": "How should content be chunked for the API?", "acceptedAnswer": { "@type": "Answer", "text": "At a natural boundary such as a section, field or record, never splitting a sentence across requests. Keep related fields together so a title and its description are translated with knowledge of each other." } }, { "@type": "Question", "name": "How do I know what needs re-translating?", "acceptedAnswer": { "@type": "Answer", "text": "Store a hash of the source alongside the translation. When the hash differs the translation is stale. Without it the system either re-translates everything each run or never re-translates at all." } } ] } ```