1"use strict";(globalThis.webpackChunkdocs||=[]).push([[1274],{43093(e,n,l){l.r(n),l.d(n,{assets:()=>d,contentTitle:()=>t,default:()=>h,frontMatter:()=>i,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"reference/multilingual","title":"Multilingual Support","description":"The D&D 5e SRD API supports multilingual responses, allowing you to request translated content in supported languages. English is always the default and fallback \u2014 if a translation is incomplete or unavailable, fields fall back to English individually, so responses are always complete documents.","source":"@site/docs/reference/multilingual.md","sourceDirName":"reference","slug":"/reference/multilingual","permalink":"/2024/reference/multilingual","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"sidebar_position":1},"sidebar":"referenceSidebar","previous":{"title":"FAQ","permalink":"/2024/faq"},"next":{"title":"Schemas","permalink":"/2024/reference/schemas"}}');var r=l(86195),a=l(94758);const i={sidebar_position:1},t="Multilingual Support",d={},c=[{value:"Currently Supported Locales",id:"currently-supported-locales",level:2},{value:"Requesting a Language",id:"requesting-a-language",level:2},{value:"Query Parameter (recommended)",id:"query-parameter-recommended",level:3},{value:"Accept-Language Header",id:"accept-language-header",level:3},{value:"Response Behavior",id:"response-behavior",level:2},{value:"Translatable Fields",id:"translatable-fields",level:2},{value:"Discovering Supported Languages",id:"discovering-supported-languages",level:2},{value:"List all supported locales",id:"list-all-supported-locales",level:3},{value:"Get a specific locale",id:"get-a-specific-locale",level:3},{value:"GraphQL",id:"graphql",level:2},{value:"Contributing Translations",id:"contributing-translations",level:2}];function o(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,a.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"multilingual-support",children:"Multilingual Support"})}),"\n",(0,r.jsx)(n.p,{children:"The D&D 5e SRD API supports multilingual responses, allowing you to request translated content in supported languages. English is always the default and fallback \u2014 if a translation is incomplete or unavailable, fields fall back to English individually, so responses are always complete documents."}),"\n",(0,r.jsx)(n.h2,{id:"currently-supported-locales",children:"Currently Supported Locales"}),"\n",(0,r.jsx)(n.p,{children:"Locale availability differs per ruleset year \u2014 the 2014 and 2024 catalogs do not have to ship the same translations."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Code"}),(0,r.jsx)(n.th,{children:"Language"}),(0,r.jsx)(n.th,{children:"2014"}),(0,r.jsx)(n.th,{children:"2024"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"en"})}),(0,r.jsx)(n.td,{children:"English (default)"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Yes"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"fr-FR"})}),(0,r.jsx)(n.td,{children:"French (France)"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"\u2014"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"pt-BR"})}),(0,r.jsx)(n.td,{children:"Portuguese (Brazil)"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Yes"})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["This table reflects locales with translated content at the time of writing. The authoritative, always-current list is served by the API itself \u2014 query ",(0,r.jsx)(n.a,{href:"#list-all-supported-locales",children:(0,r.jsx)(n.code,{children:"/api/{year}/locales"})})," to discover the locales available for a given ruleset year at runtime."]}),"\n",(0,r.jsx)(n.h2,{id:"requesting-a-language",children:"Requesting a Language"}),"\n",(0,r.jsx)(n.h3,{id:"query-parameter-recommended",children:"Query Parameter (recommended)"}),"\n",(0,r.jsxs)(n.p,{children:["Append ",(0,r.jsx)(n.code,{children:"?lang={code}"})," to any resource request. This is the recommended approach because it is explicit and cache-friendly."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"GET /api/2014/spells/acid-arrow?lang=fr-FR\n"})}),"\n",(0,r.jsx)(n.h3,{id:"accept-language-header",children:"Accept-Language Header"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"Accept-Language"})," request header is also supported per ",(0,r.jsx)(n.a,{href:"https://www.rfc-editor.org/rfc/rfc5646",children:"RFC 5646"}),". If both a ",(0,r.jsx)(n.code,{children:"lang"})," query parameter and an ",(0,r.jsx)(n.code,{children:"Accept-Language"})," header are present, the query parameter takes precedence."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"Accept-Language: fr-FR\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Language codes follow the ",(0,r.jsx)(n.a,{href:"https://www.rfc-editor.org/rfc/rfc5646",children:"BCP 47"})," standard (e.g. ",(0,r.jsx)(n.code,{children:"fr-FR"}),", ",(0,r.jsx)(n.code,{children:"pt-BR"}),")."]}),"\n",(0,r.jsx)(n.h2,{id:"response-behavior",children:"Response Behavior"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:["Translated fields are merged over the base English document on a ",(0,r.jsx)(n.strong,{children:"per-field basis"}),"."]}),"\n",(0,r.jsx)(n.li,{children:"Untranslated fields always retain their English value \u2014 responses are never partial."}),"\n",(0,r.jsxs)(n.li,{children:["The ",(0,r.jsx)(n.code,{children:"Content-Language"})," response header reflects the requested language when at least one field was translated, or ",(0,r.jsx)(n.code,{children:"en"})," when no translation exists for that document."]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"translatable-fields",children:"Translatable Fields"}),"\n",(0,r.jsx)(n.p,{children:"Only human-readable text fields are translated. Structural fields (indexes, URLs, numeric values, cross-references) always come from the English base document."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Field"}),(0,r.jsx)(n.th,{children:"Translatable"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"name"})}),(0,r.jsx)(n.td,{children:"Yes"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"desc"})}),(0,r.jsx)(n.td,{children:"Yes"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"higher_level"})}),(0,r.jsx)(n.td,{children:"Yes"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"equipment_category.name"})}),(0,r.jsx)(n.td,{children:"Yes"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"equipment_categories[].name"})}),(0,r.jsx)(n.td,{children:"Yes"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"index"})}),(0,r.jsx)(n.td,{children:"No"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"url"})}),(0,r.jsx)(n.td,{children:"No"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:"Numeric values (HP, range, duration, etc.)"}),(0,r.jsx)(n.td,{children:"No"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:"API reference objects"}),(0,r.jsx)(n.td,{children:"No"})]})]})]}),"\n",(0,r.jsx)(n.h2,{id:"discovering-supported-languages",children:"Discovering Supported Languages"}),"\n",(0,r.jsx)(n.admonition,{type:"note",children:(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"/api/{year}/languages"})," lists D&D in-world game languages (Common, Elvish, etc.). ",(0,r.jsx)(n.code,{children:"/api/{year}/locales"})," is the endpoint for API translation support."]}
1)}),"\n",(0,r.jsx)(n.h3,{id:"list-all-supported-locales",children:"List all supported locales"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"GET /api/{year}/locales\n"})}),"\n",(0,r.jsx)(n.p,{children:"Returns all languages that have at least some translated content for the given ruleset year."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-json",children:'{\n "count": 2,\n "results": [\n { "lang": "fr-FR", "url": "/api/2014/locales/fr-FR" },\n { "lang": "pt-BR", "url": "/api/2014/locales/pt-BR" }\n ]\n}\n'})}),"\n",(0,r.jsx)(n.h3,{id:"get-a-specific-locale",children:"Get a specific locale"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{children:"GET /api/{year}/locales/{lang}\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Returns ",(0,r.jsx)(n.code,{children:"404"})," if no translations exist for the requested language."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-json",children:'{\n "lang": "fr-FR",\n "url": "/api/2014/locales/fr-FR"\n}\n'})}),"\n",(0,r.jsx)(n.h2,{id:"graphql",children:"GraphQL"}),"\n",(0,r.jsxs)(n.p,{children:["The optional ",(0,r.jsx)(n.code,{children:"lang"})," argument is available on entity queries:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-graphql",children:'query {\n spell(index: "acid-arrow", lang: "fr-FR") {\n name\n desc\n }\n}\n'})}),"\n",(0,r.jsx)(n.p,{children:"Translation resolution is identical to REST \u2014 translated fields are merged before the resolver returns, with English as the per-field fallback."}),"\n",(0,r.jsx)(n.h2,{id:"contributing-translations",children:"Contributing Translations"}),"\n",(0,r.jsx)(n.p,{children:"Translations are entirely community-driven. No database access or special tooling is required."}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Fork the ",(0,r.jsx)(n.a,{href:"https://github.com/5e-bits/5e-database",children:"5e-database"})," repository"]}),"\n",(0,r.jsxs)(n.li,{children:["Create or edit a file at ",(0,r.jsx)(n.code,{children:"src/{year}/{lang}/5e-SRD-{Collection}.json"})]}),"\n",(0,r.jsx)(n.li,{children:"Include only the translatable fields for each entry \u2014 non-translatable fields are sourced from the English base automatically"}),"\n",(0,r.jsx)(n.li,{children:"Open a PR \u2014 CI validates your translation against the English source"}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.strong,{children:"Example \u2014 French spell translation entry:"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-json",children:'[\n {\n "index": "acid-arrow",\n "name": "Fl\xe8che acide",\n "desc": [\n "Une fl\xe8che verte scintillante jaillit vers une cible..."\n ],\n "higher_level": [\n "Lorsque vous lancez ce sort avec un emplacement de sort de niveau 3 ou sup\xe9rieur..."\n ]\n }\n]\n'})}),"\n",(0,r.jsxs)(n.p,{children:["See ",(0,r.jsx)(n.a,{href:"https://github.com/5e-bits/5e-database/blob/main/CONTRIBUTING.md",children:(0,r.jsx)(n.code,{children:"CONTRIBUTING.md"})})," in the database repository for full guidelines."]})]})}function h(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(o,{...e})}):o(e)}},94758(e,n,l){l.d(n,{R:()=>i,x:()=>t});var s=l(98067);const r={},a=s.createContext(r);function i(e){const n=s.useContext(a);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function t(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:i(e.components),s.createElement(a.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.