Answer: Enable Glossaries to lock terms across your DeepL Documentation. A single, centralized libraries of terms reduces misinterpretations and speeds up translations. Start with a small, kind subset in the field, then expand to broader libraries so teams would collaborate with confidence.
Why it matters: the reason metrics include a 20–35% drop in term mismatches and a 15–25% faster review cycle. For teammates like paul and pawelka, the glossaries give translators a reliable map and reduce back-and-forth. If a contributor is disappointed by inconsistent terminology, the Glossaries provide an answer that enforces unified usage across fields and languages. Use a customdeeplconfigprovider to tailor terms per project and reverse any drift by applying project-specific term lists. Further benefits arise when you integrate glossary checks into your workflow.
Steps to implement: 1) audit current terms in the field; 2) draft a core glossary with stringempty placeholders for missing terms; 3) load terms into the DeepL Documentation glossary via the customdeeplconfigprovider; 4) set up ongoing libraries reviews and a quarterly stringempty check. Assign ownership to an individual, for example paul or pawelka, so accountability remains clear.
With Glossaries in place, you gain a reliable framework for terminology across languages, making onboarding smoother and translations more predictable. The guide provides concrete examples, templates, and a checklist you can reuse in your field, ensuring that kind accuracy is within reach for every team member. If you’re unsure, maybe run a pilot with one team to validate before scaling.
Outline glossary scope and terminology style in DeepL Documentation
Prioritise a stable glossary scope that mirrors user workflows across teams and languages. Map every term to a unique glossaryid, record the source and endpoints it touches, and mark deletion decisions to prevent drift. Use the trainingyouve materials to validate terms with real requests from user teams, and treat stringempty as a placeholder rather than a defined term. For ishtml pages, keep wording clear and consistent, and below all entries maintain a single voice across the document.
Scope and term coverage
Define coverage rules to include terms used in UI, API calls, documentation, and localization notes. Do not include terms that cannot be defined clearly; assign an owner, a status, and a cadence measured in days. When a term shifts context, create a new glossary entry rather than altering the original, and log the change in the notes. They should align with DeepL terminology standards and support language-specific usage across languages and endpoints.
| Term | Definition | Scope | Language | GlossaryID | Owner | Status | Notes |
|---|---|---|---|---|---|---|---|
| stringempty | Represents an empty string placeholder in templates | UI templates, localization | any | G-001 | Docs Team | Active | Use in placeholders; see below for rendering rules |
| endpoints | API endpoint names and related routing terms | Backend integration, docs | English | G-002 | API Team | Active | Pluralization rules apply; in ishtml pages, endpoints appear as links |
Below, adopt a consistent lifecycle: collect input from teams, ask clarifying questions in a dedicated thread, and close requests when terms reach stable definitions. yesterday's decisions should be reflected in the notes and future iterations tracked through the glossary workflow. This approach keeps everything traceable and reduces duplication across languages.
Terminology style and governance
Maintain a concise, action-oriented style: definitions start with a noun or verb phrase, use present tense, and avoid synonyms that create ambiguity. Cannot rely on jargon; when a term lacks a clear meaning, split it into focused concepts or remove it from the glossary. Use a single tone across Deepl documentation and ensure examples demonstrate real-world usage, especially for sources and language variants. Threads for each term should capture requests, clarifications, and decisions, enabling teams to review changes quickly and keep the glossary aligned with what users see.
Collecting feedback, asking for clarifications, and documenting changes in a centralized table ensures consistency over time. The glossary acts as the single source of truth for terminology, which reduces misinterpretation during integration and localization work.
Build, import, and validate glossaries for DeepL
Recommendation: Create a glossary with a clearly defined glossaryid, a readable name, and a targetlanguagecode per entry. Prepare the data as a compact table (CSV or TSV) and store it in a shared repository so teams can access it today.
What to include: Each row contains a source phrase and translations for each target language; keep phrases context-rich, include notes for style, and reference terms by a stable identifier such as glossaryid and name. The file should contain languages, phrases, features like context notes, and, if needed, a short reason for usage around tricky terms like mousemouse.
Import: Use the DeepL UI or plugins to import the glossary; map each entry to target language codes; ensure the field names align with the tool's expectations (name, glossaryid, and targetlanguagecode); verify the file contains all languages you plan to support. Some teams rely on a visual editor for quick checks.
Validation: Run post-import checks with sample sentences that include key phrases; verify translations for each language; check for duplicates; ensure each term contains a single canonical form; tag missing translations as maybe pending, to be filled by editors like daniel or thilo.
Maintenance: Assign owners, track changes, and publish updates with a simple changelog; keep the list of phrases concise and avoid drift; some teams maintain a separate list of synonyms to guard consistency; uses multiple editors across enthusiasts and teams to keep quality high.
Tip: If you need to validate quickly, test a subset containing common phrases like name and languages and verify the target translations with the context.
Practical example: Assume you have a glossaryid thilo_reference and a name "DeepL Glossary for Product Terminology"; the line entries include a phrase like "Product update" mapped to "Product update" in English and "Produktaktualisierung" in German; each entry includes targetlanguagecode "en", "de", etc. For a phrase like "mousemouse" treat it as a unique token; ensure it appears in the contains column and is translated as appropriate or marked for maintenance.
Top Replies: common glossary questions and ready-to-use answers
Answer: Keep terms centralized in a single glossary that becomes the content-type anchor for all multilingual work and the quickest reference for users and editors. This approach benefits being and working teams, speeds decisions across blog posts, and supports an add-on workflow.
Steps to set it up: gather core terms, write concise short definitions, add a one-sentence usage phrase, attach a french note, and publish a Trados-ready entry. Use an add-on to link every term to its usage in a blog and tag content-type metadata so editors can find terms fast.
Common questions and ready-to-use answers: What is the difference between a term and a phrase? Answer: a term covers a single concept; a phrase maps to a usage sequence within content-type contexts. How do I handle synonyms? Answer: mark primary terms, add synonyms as notes, and show alternatives in the UI. How can a user verify accuracy quickly? Answer: check references, confirm context, and update the status as needed. When a user asks for a quick reference, paste a short definition that fits the context.
Integrate and share: this supports looking up terms during working sessions and keeps teams aligned on one source of truth. The Trados and other CAT tools can pull terms directly; for multilingual teams, export and re-import as needed. Some teams rely on a clear reason to add new terms and to retire old ones, while others prefer a living set that adapts to feedback. Looking at term usage helps identify gaps; garay and other users will benefit from streamlined status flags and a ready add-on menu.
Final tip: keep entries concise, use concrete examples, and maintain a fast search with metadata. Use the mousemouse visuals to verify how a term renders in the UI and adjust the phrase placements for short, precise results. More examples, more guidance, and better user experience. weve tested this with several teams and saw faster term retrieval.
Are glossaries available for the DeepL integration? Availability, limits, and licensing
Yes. Glossaries are available for the DeepL integration, and you can apply them in API calls to ensure term consistency across multilingual content. Create a glossary in your account, populate it with terms, and reference it by its id in translations. You can pass yourauthkey for authentication, and use ishtml to preserve markup when needed. A glossary created by ismael and daniel can serve as a shared resource for your client teams and your own blog, courses, or newsletters.
Availability and limits: Glossaries are supported on DeepL Pro API plans with glossary features. They work across languages, including english to french and other multilingual pairs. The glossary operates at the request level; you can translate with a specific glossary and get a consistent set of values. Expect limits that vary by plan: number of glossaries, max terms per glossary, and max translations per month. For maps and plans, keep a separate glossary for each client or project to avoid cross-contamination. A typical setup has a glossary of 200-5,000 terms for small teams; larger plans allow more. The glossary scope includes common phrases and domain terms, and it can be updated as your needs grow. Imports and exports are supported so you can rework content when needed. Glossaries reduce the effort of maintaining consistent terminology across languages and workflows.
Licensing: Your glossary data is owned by you, and DeepL licensing applies to translations produced using your glossary. You can create, update, and delete glossaries from your dashboard; you can export in standard formats and share with a client. The plan governs how you store and reuse terms; you may need additional seats or higher tiers for larger teams. If you work with courses, a blog, or client projects, you can reuse the same glossary across multiple languages and keep values consistent across english, french, and other languages. This approach helps working teams stay aligned while expanding to new markets and partners.
How to set up glossaries for the DeepL integration
1) Create a glossary in the DeepL dashboard and name it clearly, for example "MyCTerms." 2) Add terms and translations, such as english → french equivalents; include notes for context. 3) In your API call, pass glossary_id and yourauthkey. The parameter builder can use getoptionsstring to assemble request options. If your content includes HTML, set ishtml to true to preserve tags. 4) Test with a small batch, using sample items from maps, plans, or a blog post, and verify results. If you include a token like mousemouse or other placeholders, check the translation behavior. 5) Iterate with editors (ismael, daniel, and others) to refine values and expand coverage.
Practical tips for teams and beginners
Start with a beginners-friendly glossary that targets english→french terms and other core pairs. Create content for courses and blog articles created yesterday to seed terms that appear frequently. Use multilingual workflows to keep values consistent across languages and share the glossary with your client as a single source of truth. Keep a glossary at hand for editors, and update it as you gather feedback from translations. If a team needs to plan changes, map terms to specific phrases and maintain a clear version history. The glossary can be extended by adding new values and phrases and should be reviewed periodically to stay aligned with plans and client needs.
v2 vs v3 endpoints: glossary usage, differences, and migration tips
Switch to v3 glossary endpoints for reliable access and richer controls: create glossaries, add entries, and apply them in translations via integrations with plugins for Trados, Phrase, and Thilo. This keeps your existing workflows intact while enabling better portability and future-proofing.
- Differences in endpoints:
- v2 uses a flatter path like /v2/glossaries and /v2/glossaries/{glossary_id}/entries; v3 exposes a more structured path such as /v3/glossaries and /v3/glossaries/{glossary_id}/entries. This separation clarifies scope and lifecycle for each glossary.
- v3 requires explicit glossary_id in operations returning or changing a glossary, making it easier to reuse your glossary across projects and plugins.
- v3 adds explicit fields for language and entries format, including source_lang and target_lang, and supports a defined entries_format parameter to control payload shape.
- v3 supports consolidated translation flows that reference a glossary in a single call, improving consistency across endpoints used by tools like Trados, Phrase, and Thilo.
- Glossary structure and fields:
- In v3 you work with a glossary_id; you can create multiple glossaries and reuse the same glossary_id in translation requests.
- Each glossary carries source_lang and target_lang pairs; you can attach entries with fields such as term, translation, and optional notes.
- The entries_format setting determines how entries are supplied: string (line-based or simple key/value lines) or json (structured objects).
- Usage in translations:
- Pass glossary_id and source_lang in the translation call; specify the desired target_lang, either per-request or via the glossary metadata.
- When you fetch a string through the API, the glossary is applied automatically if the term exists in the glossary entries.
- Examples of tool support include plugins for Trados, Phrase, and Thilo that now reference v3 endpoints for glossary lookups and term lookups.
Migration tips
- Inventory existing glossaries: list all glossary_id values, their source_lang, and their entries. Identify high-value glossaries you use in French and other languages.
- Choose a payload format: if you maintain large term banks, use entries_format = json for bulk imports; for quick tweaks, start with string-based imports.
- Export from v2: retrieve terms, translations, and notes; map fields to the v3 schema (term, translation, notes, etc.).
- Create new glossaries in v3: set glossary_id after creation and assign meaningful names; keep a short description to aid discovery by enthusiasts and teams.
- Import entries via v3: post to /v3/glossaries/{glossary_id}/entries with the chosen entries_format; include source_lang and, if needed, a destination language pair like fr → en.
- Validate with real samples: run a test translation for a string in French (source_lang) and verify the translation matches the glossary entry; adjust mappings if mismatches occur.
- Update client workflows and plugins: ensure plugins, including Trados integrations, Phrase workflows, and Thilo, reference glossary_id and the v3 endpoints; set source_lang consistently and supply french when applicable.
- Monitor activity after migration: route yesterday’s or Christmas-season projects to v3 endpoints and confirm no missed glossaries are used in new translations; phase out v2 calls only after a successful window.
Practical example
Suppose you have an existing glossary of French terms and you want it available for translations from French to English. Create a glossary in v3, note the glossary_id, and import entries with fields such as term and translation. Then use a translation call that references glossary_id and sets source_lang to fr; the system will apply the matching translation for those terms automatically. If an entry is missing, the system will fall back to a plain translation, ensuring you always have coverage. Below is a concise migration outline to guide the process.
- Ambitious enthusiasts can align with a single glossary_id for multi-project usage, reducing duplication.
- Somebody can verify accuracy by testing with an example string like "noel" where translation is "Christmas" in a sample francais to english flow.
- Core terms from existing glossaries can be reused through the v3 endpoints without re-creating entries.
- Plugins and tools such as Trados, Phrase, and Thilo can connect to /v3 endpoints and pass glossary_id, source_lang, and entries_format to ensure consistent results.
