Termbase Template (ISO 704, TBX)

Termbase: [Product, domain or organisation name]

Terminology register for a product, documentation set or organisation. Each entry describes one concept, gives its definition, its terms with usage status (preferred, admitted, deprecated), context, source, related concepts and equivalents in each target locale. Definition and term rules follow the principles of ISO 704:2022 (Terminology work: Principles and methods, 4th edition), written here in original wording, and the register columns map to data categories used by TermBase eXchange (TBX, ISO 30042:2019) so the table can be exported to translation and authoring tools. Replace every [bracketed] value and every row marked Example. Worked examples use Corvid Commerce, a fictional SaaS retailer, and the terms of its checkout and data platform.

Document control

Approvals

Revision history

Contents

1. Purpose, scope and users
2. Roles and entry lifecycle
3. Entry model
4. Field definitions and TBX mapping
5. Definition rules
6. Term selection and usage status
7. Terminology register
8. Equivalents per locale
9. Do-not-translate terms
10. Concept relations
11. Requests and change log
12. Quality checks
13. Export and exchange
14. Glossary and references

1. Purpose, scope and users

This termbase records the concepts that [Product name] content depends on and the words used to name them, so that the UI, documentation, support articles, training and translations use the same term for the same thing.

Include a concept when at least one of these is true:

1. It is specific to the product or domain and readers may not know it.
2. Teams use more than one word for it, or one word for more than one concept.
3. Translators have asked about it, or translations of it have differed.
4. A wrong term would cause a legal, financial or safety misunderstanding.
5. It is a product, feature or event name that must stay fixed.

Exclude general vocabulary that any dictionary covers with the meaning you intend, and internal code names that never reach users.

2. Roles and entry lifecycle

Entry status (above) is about the whole concept entry. Usage status (preferred, admitted, deprecated) is about each term inside an entry and is set in section 6. An approved entry can hold deprecated terms; that is how the termbase tells writers which old words to stop using.

3. Entry model

The termbase is concept-oriented: the entry is the concept, and terms hang below it. Each entry has three levels, which match the TBX structure of a concept entry, language sections and term sections.

A definition written in a target language is a translation of the concept definition; it must not narrow or widen the concept. If a locale genuinely needs a different concept (for example a legal term that only exists in one jurisdiction), create a separate entry and link the two.

4. Field definitions and TBX mapping

Use the controlled values exactly as listed. The mapping above follows TBX-Basic Version 4 (TerminOrgs, 2025, compliant with ISO 30042:2019), where usage status is <termNote type="usageStatus"> with the values preferred, admitted and deprecated, and term type takes fullForm, acronym, abbreviation, shortForm, variant or phrase. Older TBX-Basic versions and some other dialects encode usage status as administrativeStatus with values such as preferredTerm-admn-sts, admittedTerm-admn-sts and deprecatedTerm-admn-sts. Confirm the picklists for the dialect you export before the first handoff.

5. Definition rules

A definition states what a concept is, so that a reader can tell it apart from related concepts. Write each definition to these rules:

1. One concept, one definition. If the definition needs "or" to cover two different things, there are two concepts.
2. Start from the nearest broader concept, then add what makes this one different. "Partial refund: refund of less than the full amount captured for an order" names the broader concept (refund) and the distinguishing characteristic (less than the full amount).
3. Make it substitutable. The definition should be able to replace the term in a sentence without changing the meaning. That is why it starts with a noun phrase for a noun, not with "A term that" or "When you".
4. Do not repeat the term or use it in disguise. "Refund: the act of refunding" defines nothing. Also avoid two definitions that point at each other.
5. Say what it is, not only what it is not. Use a negative only when the absence of a characteristic is what defines the concept.
6. Keep usage, procedures and examples out of the definition. Put them in the context or note fields.
7. Use terms that are defined in the termbase or generally known. Link other entries in related concepts instead of explaining them inline.
8. Write one phrase, not a paragraph. No initial article, no full stop in the definition column, and no more detail than needed to separate the concept from its neighbours.
9. Match the scope of the product. Define the concept as the product uses it; if the industry meaning differs, say so in the note.

6. Term selection and usage status

When a concept has more than one candidate term, choose the preferred term with these criteria, in this order:

1. It is already used correctly in the shipped UI, and changing it would confuse users more than it helps.
2. Its meaning can be inferred from its parts by the intended audience.
3. It fits the existing pattern of related terms (for example, all payment events use the same noun and verb pattern).
4. It is short enough for UI labels without becoming an unclear abbreviation.
5. It translates cleanly; terms built on idioms or wordplay are avoided.
6. It is inclusive and neutral (no terms such as "whitelist" or "master/slave").

Each entry has exactly one preferred term per locale it covers. A deprecated term always sits in an entry that also has a preferred term, so writers know what to use instead. Some older TBX dialects add a superseded value for terms replaced over time; this termbase records that history in the note field rather than as a fourth status, and TBX-Basic Version 4 has no such value.

7. Terminology register

Note on TERM-0004 and TERM-0009: the action (to refund) and its result (a refund, money returned) are different concepts, so they are two entries linked as associative. Use one entry with several term rows only for designations of the same concept, such as a full form and its acronym.

8. Equivalents per locale

Equivalents name the same concept in a target locale. The definition stays the one agreed in the source language; add a definition in the target language only when reviewers need it, and keep its meaning identical. Each row carries its own usage status, because a preferred source term can have an admitted or deprecated form in a locale.

Rules for equivalents:

1. Translate the concept, using the definition and context in section 7, not the English word.
2. Record one preferred equivalent per concept and locale; list other forms as admitted or deprecated rows with a note.
3. Check every equivalent against the do-not-translate list in section 9 so the two never disagree.
4. Note grammatical information translators need, such as gender, plural or counters, in the Note column.
5. Re-review equivalents when the source definition changes; mark them "To review" until the locale reviewer approves again.

9. Do-not-translate terms

These terms keep the same form in every locale. They are exported with part of speech properNoun (for names) or with a note, and the Localization Brief (docs/localization-brief) refers to this section.

10. Concept relations

Concept relations help writers choose between a general and a specific term and help translators see whether two terms are siblings or synonyms. Record three relation types:

11. Requests and change log

Anyone can request a new term, a new equivalent or a status change. A request includes the proposed term, the concept it names, a real context sentence, a source and the locales affected.

Decisions that change a preferred or deprecated term are announced to writers, engineers and the localisation vendor, because they change the linter vocabularies and translation memories.

12. Quality checks

13. Export and exchange

Generate every downstream copy from this register; never edit an export by hand.

Example TBX-Basic Version 4 fragment for TERM-0003 (a valid file wraps it in <tbx type="TBX-Basic" style="dca" xml:lang="en"> with a <tbxHeader>; validate against the schema of the dialect you export):

<conceptEntry id="TERM-0003">
  <descrip type="subjectField">Checkout and payments</descrip>
  <langSec xml:lang="en-US">
    <descrip type="definition">Refund of less than the full amount captured for an order</descrip>
    <termSec>
      <term>partial refund</term>
      <termNote type="partOfSpeech">noun</termNote>
      <termNote type="usageStatus">preferred</termNote>
      <descrip type="context">You can issue several partial refunds until the captured amount is used up.</descrip>
    </termSec>
  </langSec>
  <langSec xml:lang="de-DE">
    <termSec>
      <term>Teilerstattung</term>
      <termNote type="partOfSpeech">noun</termNote>
      <termNote type="grammaticalGender">feminine</termNote>
      <termNote type="usageStatus">preferred</termNote>
    </termSec>
  </langSec>
</conceptEntry>

CSV export columns, in order: id, subject_field, definition, locale, term, part_of_speech, usage_status, term_type, grammatical_gender, context, source, related, note, publish. Quote every field, keep line breaks out of cells, and save as UTF-8 so CJK and Arabic terms survive.

For the Vale vocabulary, the export writes preferred and admitted source-language terms to accept.txt and deprecated terms to reject.txt, as described in the Docs Contribution Guide (docs/docs-contribution-guide). Terms that need case-insensitive matching are exported with the (?i) prefix.

14. Glossary and references

Standard and licence note

Structure aligned with ISO 704:2022 (principles and methods of terminology work) and ISO 30042:2019 (TermBase eXchange), which are copyrighted by ISO. The definition and term selection rules are original wording written for this template after the general principles of ISO 704; no text, table or definition from the standard is reproduced. TBX element and data category names are cited only so that the register can be exported; check the data category list and schema for your dialect at tbxinfo.net, and the current editions at iso.org, because a revision of ISO 30042 is in development. Corvid Commerce and every example entry are fictional. Original text written for this collection. Template licence: MIT.