--- title: OpenAPI Overlays for Translating and Localizing One... description: Maintaining separate translated copies of an OpenAPI spec leads to contract drift and inconsistency. OpenAPI Overlays solve this by treating translation as a... canonical: https://daily.dev/posts/openapi-overlays-for-translating-and-localizing-one-canonical-spec-uuthegatj twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: OpenAPI Overlays for Translating and Localizing One Canonical Spec | daily.dev og:description: Maintaining separate translated copies of an OpenAPI spec leads to contract drift and inconsistency. OpenAPI Overlays solve this by treating translation as a... og:url: https://daily.dev/posts/openapi-overlays-for-translating-and-localizing-one-canonical-spec-uuthegatj og:image: https://api.daily.dev/og/posts/UUthEGATJ.png og:image:alt: OpenAPI Overlays for Translating and Localizing One Canonical Spec og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # OpenAPI Overlays for Translating and Localizing One Canonical Spec **[API Evangelist](https://daily.dev/sources/apievangelist)** · 4 min read · 0 upvotes · 0 comments ## Summary Maintaining separate translated copies of an OpenAPI spec leads to contract drift and inconsistency. OpenAPI Overlays solve this by treating translation as a presentation concern rather than a contract concern. One canonical English spec is kept as the source of truth, while per-language overlay files replace only human-readable fields like summaries, descriptions, and error message examples. A concrete Spanish overlay example demonstrates translating both endpoint summaries and Problem Details error responses while leaving contract elements (paths, header names, media types) untouched. The recommended folder structure is locale-first (overlays/es/, overlays/de/) with a build pipeline that generates localized specs on demand. The core argument: any team maintaining multiple copies of an OpenAPI file for different languages has already introduced a second source of truth and will eventually pay for it. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### How do I translate error messages in an OpenAPI spec without forking the whole file into multiple languages? Use an OpenAPI Overlay targeted at the specific JSON path of the error example, such as $.components.responses.TooManyRequests.content['application/problem+json'].example, and update only the title and detail strings. The overlay extends the canonical English spec and rewrites just the human-readable prose, leaving header names like RateLimit-Reset untouched since those are part of the contract, not translatable text. _daily.dev surfaces practical OpenAPI overlay patterns for teams localizing error messages without forking specs._ ### What folder structure should I use for organizing OpenAPI translation overlays for multiple languages? Structure overlays locale-first, with a top-level folder per language such as overlays/es/, overlays/de/, and overlays/fr/, rather than organizing by concern like summaries or errors. Adding a new language becomes adding a single folder, and a build pipeline loops through each locale directory, applies its overlay to the canonical spec, and emits an output file like dist/products-api.es.yaml. _Teams scaling API localization across languages can track patterns like this on daily.dev._ ### Should translated OpenAPI documentation be a separate source file or generated from the original spec? Localized OpenAPI documentation should be generated at build time from a single canonical spec, not maintained as a separate copy. Translation is a presentation concern, not a contract concern: paths, operationIds, schema property names, status codes, and header names stay in the original language, while only prose like summaries, descriptions, and example payloads gets translated via an overlay applied on demand. _daily.dev helps developers stay current on API contract and localization practices like this one._ ## Similar posts on daily.dev - [OpenAPI Overlays Let One Products API Speak Four Languages](https://daily.dev/posts/openapi-overlays-let-one-products-api-speak-four-languages-9dpds4czz) · API Evangelist · 0 upvotes · 0 comments - [OpenAPI Overlays for Adding Tool-Specific Content Without Polluting the Spec](https://daily.dev/posts/openapi-overlays-for-adding-tool-specific-content-without-polluting-the-spec-np7suyu3c) · API Evangelist · 0 upvotes · 0 comments - [OpenAPI Overlays for Separation of Concerns When You Do Not Own the Spec](https://daily.dev/posts/openapi-overlays-for-separation-of-concerns-when-you-do-not-own-the-spec-zhy9th4pq) · API Evangelist · 0 upvotes · 0 comments - [The Many Use Cases for OpenAPI Overlays](https://daily.dev/posts/the-many-use-cases-for-openapi-overlays-1gjpvrair) · API Evangelist · 0 upvotes · 0 comments - [OpenAPI Overlays for Improving Developer Experience: Enriching a Thin, Code-Generated Spec](https://daily.dev/posts/openapi-overlays-for-improving-developer-experience-enriching-a-thin-code-generated-spec-qiejsxc37) · API Evangelist · 0 upvotes · 0 comments --- Tags: [#architecture](https://daily.dev/tags/architecture), [#backend](https://daily.dev/tags/backend), [#openapi](https://daily.dev/tags/openapi), [#localization](https://daily.dev/tags/localization) [View this post on daily.dev](https://daily.dev/posts/openapi-overlays-for-translating-and-localizing-one-canonical-spec-uuthegatj) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"OpenAPI Overlays for Translating and Localizing One Canonical Spec","url":"https://daily.dev/posts/openapi-overlays-for-translating-and-localizing-one-canonical-spec-uuthegatj","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/openapi-overlays-for-translating-and-localizing-one-canonical-spec-uuthegatj"},"datePublished":"2026-07-09T13:27:49.791Z","dateModified":"2026-09-14T06:37:07.022Z","description":"Maintaining separate translated copies of an OpenAPI spec leads to contract drift and inconsistency. OpenAPI Overlays solve this by treating translation as a...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/865556c79bdaecbd69602dfeaa722a50?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/865556c79bdaecbd69602dfeaa722a50?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"API Evangelist","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"API Evangelist","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/a36244ae67bc4f41a605f780267ecb5f","url":"https://daily.dev/sources/apievangelist"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/openapi-overlays-for-translating-and-localizing-one-canonical-spec-uuthegatj","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"architecture,backend,openapi,localization","timeRequired":"PT4M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"API Evangelist","item":"https://daily.dev/sources/apievangelist"},{"@type":"ListItem","position":3,"name":"OpenAPI Overlays for Translating and Localizing One Canonical Spec"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/openapi-overlays-for-translating-and-localizing-one-canonical-spec-uuthegatj#faq","mainEntity":[{"@type":"Question","name":"How do I translate error messages in an OpenAPI spec without forking the whole file into multiple languages?","acceptedAnswer":{"@type":"Answer","text":"Use an OpenAPI Overlay targeted at the specific JSON path of the error example, such as $.components.responses.TooManyRequests.content['application/problem+json'].example, and update only the title and detail strings. The overlay extends the canonical English spec and rewrites just the human-readable prose, leaving header names like RateLimit-Reset untouched since those are part of the contract, not translatable text. daily.dev surfaces practical OpenAPI overlay patterns for teams localizing error messages without forking specs."}},{"@type":"Question","name":"What folder structure should I use for organizing OpenAPI translation overlays for multiple languages?","acceptedAnswer":{"@type":"Answer","text":"Structure overlays locale-first, with a top-level folder per language such as overlays/es/, overlays/de/, and overlays/fr/, rather than organizing by concern like summaries or errors. Adding a new language becomes adding a single folder, and a build pipeline loops through each locale directory, applies its overlay to the canonical spec, and emits an output file like dist/products-api.es.yaml. Teams scaling API localization across languages can track patterns like this on daily.dev."}},{"@type":"Question","name":"Should translated OpenAPI documentation be a separate source file or generated from the original spec?","acceptedAnswer":{"@type":"Answer","text":"Localized OpenAPI documentation should be generated at build time from a single canonical spec, not maintained as a separate copy. Translation is a presentation concern, not a contract concern: paths, operationIds, schema property names, status codes, and header names stay in the original language, while only prose like summaries, descriptions, and example payloads gets translated via an overlay applied on demand. daily.dev helps developers stay current on API contract and localization practices like this one."}}]} ```