Glossary/Glossentry Best Practices for Translation

Hi @sschnelbach ,

You're raising a very valid concern — this is a known challenge when using DITA glossary entries (glossentries) in localized output, especially for languages with rich inflection (e.g., German, Russian, Finnish, etc.).

1. Avoid In-line Glossentry Terms for Inflected Languages

You're absolutely right — directly embedding a <glossref> or <xref href="...glossary..."> term in a sentence can break grammatical rules in many target languages. For example:

  - English: "Click the engine button."

  - German: "Klicken Sie auf den Motor." (Here "Motor" changes form based on case.)

Best practice: Use plain text in the sentence and link the glossary term only where grammatically appropriate, such as:

  - In tooltips

  - In standalone lists

  - At the start or end of a paragraph

2. Use <glossref> Only When Full Control Exists

The <glossref> element assumes the term can be inserted verbatim. This works best when:

  - The term is a proper noun or acronym (unchanging)

  - The language has minimal or no inflection

  - It's used in isolation or short sentences

For complex grammars, avoid <glossref> and instead use localized wording + a footnote or endnote-style link to the term.

3. Consider Glossary Links as Non-linguistic Metadata

Treat glossary links more like index terms or semantic tags, and avoid embedding them inline unless you're sure the translation engine or LSP can handle it with appropriate context.

4. Use Phrase-Level Wrapping

In some tools or custom PDF plugins (like in AEM Guides with DITA-OT plugins), you can:

Wrap glossary terms in a phrase-level element (e.g., <ph outputclass="gloss-link">)

Then configure output transforms to generate tooltip-style or parenthetical references only when needed

Example:

This gives translators freedom to translate the sentence properly while the glossary term remains accessible.

5. Localized Glossary Strategy

If you use glossentries, you should ideally translate the glossary terms themselves and ensure the localized glossaries contain:

  - Localized glossterm values

  - Localized definitions

  - Culture-specific usage if needed

In AEM Guides:

  - Glossary entries can be managed per language

  - Make sure your translation workflow supports glossentry localization separately from topic translation

6. Alternatives to Inline Listing

Instead of:

"Glossary Terms Used: term1, term2"

You might try:

See also: [Term1], [Term2] — listed in a "Related Terms" or "Key Terms" section with proper styling.

Use a related-links or custom role to style this better in PDF output.

Regards,
Amit