Troubleshooting glossary term imports

If your CSV file contains characters that our Glossary doesn't support in the term column, the importer displays feedback messages in the Map your columns step to identify issues and let you know what to do about them.

You'll run into two main types of errors:

1. Unsupported character in terms: The import will still work, but we'll remove the unsupported characters from terms. These errors are identified with a yellow warning callout in the import modal. Refer to Unsupported characters in terms for more information on this error.
2. Unsupported characters in definitions: If definitions contain unsupported characters, the import can't move forward. You must resolve these issues in your CSV file before you can import. These errors are identified with a red failure callout at the top of the import modal. Refer to Unsupported characters in definitions for more information on this error.

Unsupported characters in terms

The most common issue you'll run into in the importer is unsupported characters in terms. You can still run the import with these errors; we'll just remove the unsupported characters from the terms.

We warn you of these issues in the Map your columns step, displaying them between the column mappings and the import preview:

Sample of unsupported characters in terms warning

What the error looks like

The error displays in a warning callout in the Map your columns step of the glossary terms import and will look something like this:

Note that it identifies the term and tells you how the term will import instead.

Why this error occurs

Due to autohighlighting constraints, glossary terms can only contain: letters, numbers, spaces, dashes, underscores, and apostrophes.

Any other character, including other forms of punctuation including parentheses, slashes, numeric operators, ampersands, and special characters like © or ® will trigger this error.

How to fix it

You technically don't have to fix this issue. The importer will automatically strip out the unsupported characters from terms, as outlined in the error itself.

However, there are two cases when you may want to resolve the issue, outlined below.

Fix supported character encoding issue

If the character is something that you think should be supported based on our Glossary formatting documentation, such as an accented character, it's most likely that your CSV is not encoded for UTF-8. Our importer only supports UTF-8 encoding, so supported characters encoded in some other way can cause issues.

If you're viewing your CSV in Microsoft Excel, the easiest way to fix this issue is to resave the CSV in Excel as CSV UTF-8 file format. This will automatically encode any accents or special characters in the CSV file as UTF-8, which our importer fully supports.

To make this change:

1. Open the CSV file in Microsoft Excel.
2. Select File > Save As.
3. When the Save As options appear, use the file format dropdown to select CSV UTF-8 (Comma delimited) (*.csv).
4. Repeat your glossary term import using the newly-saved file.

Fix truly unsupported character

If just removing the unsupported character will remove something important, you'll likely want to edit the CSV file directly before importing.

For example, in our sample warning message, it warned us that "Caf� will import as Caf". Since the underlying word is supposed to be Cafe, we could either:

• Edit our CSV so the term doesn't include the special character, such as "Cafe"
• Take note of this list in the warning message and edit "Caf" to "Cafe" after the import completes

In both cases, you'll want to take note of any terms that lose characters, since you may need to make a long-term process change to handle them in terms of how the term is highlighted. For example, our other error switched R&D to RD. Our authors will likely always still use R&D in our documentation, so they would need to Add glossary definitions in articles manually for R&D.

Unsupported characters in definitions

If your definitions contain unsupported characters, the import can't move forward until you resolve them.

We warn you of these issues in the Map your columns step, displaying them at the top of the modal:

Sample of unsupported characters in definitions warning

What the error looks like

The error displays in a failure callout in the Map your columns step of the glossary terms import at the top of the modal and will look something like this:

Note that it identifies only the row number with the issue, not which column is the problem. The issue can occur in both display titles and definitions.

Why this error occurs

Our importer only supports UTF-8 character encoding. Characters using other encoding will trigger the error.

How to fix it

You must fix this issue before you can complete the import.

The error message will identify which rows include unsupported characters. Open your CSV file and review the identified row numbers for unusual characters, such as accents, emojis, or other values.

There are two approaches to fixing this issue.

Fix issue in Excel

If you're viewing your CSV in Microsoft Excel, the easiest way to fix this issue is to resave the CSV in Excel as CSV UTF-8 file format. This will automatically encode any accents or special characters in the CSV file as UTF-8, which our importer fully supports.

To make this change:

1. Open the CSV file in Microsoft Excel.
2. Select File > Save As.
3. When the Save As options appear, use the file format dropdown to select CSV UTF-8 (Comma delimited) (*.csv).
4. Repeat your glossary term import using the newly-saved file.

Fix issue outside of Excel

Excel or other spreadsheet programs will sometimes hide or display nothing for certain characters, especially if you've already tried converting to UTF-8 and the characters somehow became corrupted.

If you can't find any unsupported characters using one of those programs, try these steps instead:

1. Find wherever you have the CSV file stored on your computer.
2. Right-click and select Open With.
3. Choose a text editor to open the CSV, such as Notepad, Notepad++, Visual Studio Code, or any other basic text editor you have installed on your computer.
4. Text editors generally either display the special characters outright or they'll display an icon when they're unable to display a character (such as �). Look for an icon like that, an unusual character, or any kind of weird code/characters in the rows identified in the error message.
5. Delete all occurrences of the unknwoen character from the CSV in the text editor.
6.  Be sure to Save your CSV file.
7. Repeat your glossary term import using the newly-saved file.

If you're continuing to get glossary import errors and you can't figure out why, please contact us and include a copy of the CSV file. Our support owls should be able to help get things sorted out.