How to Format Your XLSX File for Glossary Import
wxrks reads a glossary import file by matching the column headers in its first row, not by fixed column positions — so getting those header names and the file's layout exactly right is what determines whether your terms, definitions, and custom attributes come in correctly. This article is the definitive reference for that exact layout.
💡 Who is this for? This guide is for Account Admin who needs to format an XLSX file so a glossary import applies the right terms, statuses, and custom attributes on the first try within the wxrks platform.
Before you import
The Import File button lives on the glossary's own page (Context > Glossaries > select a glossary). It only accepts .tbx or .xlsx files — not .csv or .xls — and you can select up to 60 files in one go.
Only Account Admin can see and use this button — glossary import requires the GLOSSARY_create permission, which isn't granted to Project Manager or Vendor roles. If you don't see Import File on a glossary you expect to manage, ask your account's Account Admin to run the import or to grant you that role.
There's no downloadable template. wxrks doesn't ship a sample import file or a "download template" option. The reliable workaround: export any existing glossary as .xlsx (Actions > Export > choose the XLSX format) and reuse its header row — export and import share the same header vocabulary, so a file that came out of wxrks is already formatted correctly to go back in. See How to export the Glossary for the full download flow.
How wxrks reads the file
Only the first sheet in the workbook is read. If you're editing an exported file, keep everything on that first sheet.
The first row must be a header row — a file without one fails to import at all.
Headers are matched by their exact text, case-insensitively (extra leading/trailing spaces are trimmed, but there's no fuzzy matching) — a column titled
status,Status, orSTATUSall work the same way.Each row is one concept. wxrks groups every language's term for that concept onto a single row.
Column layout: one repeating block per language
A valid file needs exactly one required thing: at least one column headed with a language code. Everything else is optional. The full pattern looks like this:
Concept ID, en_us, [en_us attributes...], pt_br, [pt_br attributes...], ...
Concept ID (optional, one column, shared across all languages in the row) — paste an existing concept's UUID to add this row's terms to that concept instead of creating a new one. Leave it blank, or use a value that doesn't match any existing concept, and wxrks creates a new concept for the row.
Language column (required, one per language) — headed with the exact language code, e.g.
en_usorpt_br. Both underscore (en_us) and hyphen (en-us) separators work, in any case. This column holds the actual term text for that language.Attribute columns (optional, following their language column) — any of the fields below, or a custom attribute (see next section).
The attribute columns wxrks recognizes for each language, in the order wxrks itself uses when you export a glossary (matching this order isn't required — headers are matched by name, not position — but it keeps a hand-edited file consistent with an exported one):
Header | What it sets | Accepted values |
| Updates an existing term instead of creating a new one | A term's UUID |
| The term's approval state |
|
| The term's definition | Free text |
| Whether the term should never appear in a translation | Boolean — see the note below |
| Whether the term is case-sensitive | Boolean — see the note below |
| Usage notes for the term | Free text |
| Grammatical category | Noun, Pronoun, Adjective, Determiner, Verb, Adverb, Preposition, Conjunction, Interjection, Acronym, Other, Proper Noun, Undefined |
| Grammatical gender | Masculine, Feminine, Neutral, Undefined |
| An internal note about the term | Free text |
| Whether the term is a full term or an acronym | Full, Acronym |
For Status, Part of Speech, Gender, and Term Type, spaces, hyphens, and underscores are interchangeable and case doesn't matter — under review, Under-Review, and UNDER_REVIEW all resolve the same way.
Example header row
A file with English and Brazilian Portuguese terms, a couple of standard attributes, and one custom attribute might look like this:
|
|
|
|
|
|
|
|
(blank) | Widget | Approved | false | Hardware;Software | Hardware;Software;Marketing | Bugiganga | Approved |
Because Concept ID is blank, this row creates a new concept with two terms ("Widget" in English, "Bugiganga" in Portuguese) and one custom attribute, Category, set to Hardware and Software on the English term.
Adding custom attributes
Any header inside a language's block that isn't one of the fields above (and isn't Concept ID) is imported as a custom attribute on that language's term. Name it AttributeName:Type, where Type is one of:
single_value— a single free-text value (this is also the default if you omit:Typeentirely, or use a type wxrks doesn't recognize)single_select— one value chosen from a predefined listmulti_select— multiple values in one cell, separated by semicolons (e.g.Hardware;Software)
⚠️ A header ending in :options is not a place to enter a value on every row. It declares the attribute's allowed values, entered once, in row 2 (the file's first data row), semicolon-separated — any content in that column on other rows is ignored. The per-row values themselves still go in the separate AttributeName:Type column with the same attribute name. In the example above, Category:options in row 2 sets the full allowed list (Hardware;Software;Marketing) for the Category attribute, while Category:multi_select carries each row's actual value(s). Mixing these up — typing per-row values into the :options column, or leaving it off when you meant to expand the allowed list — is one of the easiest mistakes to make in an import file.
Behavior to know before you import
A row is silently skipped, not reported as a failed import, when its language code isn't one wxrks recognizes, or when that language's own term-text cell is blank. If an import's concept count looks lower than you expected, check for rows like this rather than assuming something else went wrong.
ForbiddenandCaseonly read the exact texttrue(any capitalization) as true. Anything else in that cell —1,yes, or simply leaving it blank — is read as false; there's no separate "unset" state.Importing doesn't overwrite a concept wholesale — pairing a row's
Concept IDwith an existing concept adds or updates just the terms present in that row, without touching that concept's other languages.
This article covers the main glossary Import File flow described above. The Terminology Board has its own, separate XLSX upload for proposing terms into its review workflow — see Terminology for that format.
Related articles
All about Glossaries — what a Glossary is and how it fits into wxrks's terminology system.
How to create a Glossary — creating a Glossary and linking it to an Organizational Unit and a project.
How to add new concepts to glossaries — adding and editing concepts and terms one at a time, from the Glossary page or the Editor.
How to export the Glossary — downloading a Glossary's content, including as the XLSX template this article recommends.
Learning Terms — the automatic, AI-assisted alternative to importing terms by hand.