Uploading terms

Producers have two options to add terms within the Vocabulary Tool:

Add terms individually
Add a bulk upload of terms

To add an individual term, producers should:

Select the New Term button in the top-right corner of the Terms List tab.
Add a term code - make sure this isn't a duplication of an existing code.
Fill in the Standard Length translations section of your chosen language.
Select save to add your new term to the Terms List page.

This is the minimum you need to do to add a term. Add much more information to improve the discoverability of your term, by following our how to manage and edit terms guide.

Adding a bulk upload of terms

To bulk upload multiple terms, producers need to use a CSV file to define all terms with all the translations and import them with a few simple steps.

To upload a vocabulary file for the first time, download a template which you find by:

Selecting the Terms Upload tab.
Selecting the Download a sample file button to open a sample template.

You must delete the sample terms before adding your own.

An example of the vocabulary-tool-sample.csv:

When opening the CSV file, you may find it displays like:

To change this, explicitly define the separator in your editor (usually the semicolon, but not always).

If using Microsoft Excel 365, you must:

Select Column A and click its header
Go to the Data menu
Find and click the Text to Columns button
Select delimited file type, then Next
Select the correct separator (Semicolon in most cases), then Finish

If this doesn't work, please contact your Deltatre project/product lead.

Understanding the CSV structure

The CSV file has seven columns – here’s a guide to what each column represents, and which columns must always be filled in.

A. Code

This is the Term Code, which is the hyphenated copy that signifies what a term is (for example, new-wonderful-term). Each term code is unique and can’t be duplicated in the Vocabulary Tool.
A code must always be added.

B. Term type

Allows producers to classify terms by their length.
The default term types are word, combination of words and sentence. But it’s possible to set custom term types.
When adding a term type, it can only be associated to the culture nd-nd. This means the culture is neutral and the term type is not associated to a given language. See E. Culture for more details.
Term types don’t always need to be added.

C. Context

Allows producers to classify terms by their category.
The default context types are menu, module, page, content, navigation and SEO metadata. But it’s possible to set custom context types.
When adding a context of use, it can only be associated to the culture nd-nd. This means the culture is neutral and the term type is not associated to a given language. See E. Culture for more details.
A context of use doesn’t always need to be added.

D. Description

Allows producers to add a description of what the term is, and what job it does on your product. For example, this term is the headline for the Latest News section on the homepage.
When adding a description, it can only be associated to the culture nd-nd. This means the culture is neutral and the term type is not associated to a given language. See E. Culture for more details.
Descriptions don’t always need to be added.

E. Culture

Allows producers to add the languages their terms can be translated into.
Languages must be written using 5 characters, for example en-gb for British English or it-it for Italian.
Producers can find the correct country code (which is always the Alpha-2 code) using this search tool.
Each language a term is translated into must be added on a different row. For example, translations of the same term in both en-gb and it-it would have separate rows.
Each term must have a neutral culture (nd-nd). Only the following can be added to a nd-nd neutral culture row: B. Term type, C. Context of use, and D. Description.
A culture must always be added.

F. Standard label

Allows producers to add the full-length translation of their term.
When adding a standard label, it can only be associated to language cultures (never the nd-nd culture).
Standard labels must always be added.

G. Short label

Allows producers to add the short-length translation of their term.
When adding a short label, it can only be associated to language cultures (never the nd-nd culture).
Short labels don’t always need to be added.

Editing and updating a CSV file

Instead of editing terms individually on a Term Detail page, producers can update and upload multiple terms at once via one upload. See below for version one of an example CSV file:

See below for version two of the same example CSV file, with updates to terms added in red, and new terms added in green.

To update an existing list of terms,

Select the Terms Upload tab.
Select the Download global.csv file button, which opens a sample template.

After downloading the file, producers can change all the values of existing terms – except for the term Code and Culture.

Producers can add new terms by editing the seven sections listed in this Understanding the CSV file structure section. Producers can either make edits to a pre-existing file, or they can upload a new CSV file. If uploading a new CSV file, new terms are added to the ones already in the Vocabulary Tool system from previous uploads.

When adding new terms, it is important not to use existing Term Codes – as this may affect the upload process.

Uploading your CSV file

Producers can upload their CSV files in two ways:

Drag and drop the file into the Upload your new vocabulary file section of the Upload Terms
Select the browse button on the Upload your new vocabulary file section of the Upload Terms page and add a file from your computer.

When the new file has uploaded, it appears at top of the list on the Upload Terms page.

The new file shows the following information:

File name
Number of terms uploaded
Languages covered by the CSV file
The name of the user who uploaded the file
Icon showing the status of the upload (Queued, In Progress, Completed or Error)

Troubleshooting

Errors

If there’s an issue with your upload an error message displays, showing a list of issues blocking the CSV upload.

This means the CSV file hasn't been filled in correctly. For example, a required cell is blank.

Warnings

Sometimes, the CSV file contains errors that won't block the upload. In this case, the Vocabulary Tool identifies the errors through a warning message, asking if you wish to continue with the upload.

The Vocabulary Tool only accepts files with the .csv extension that are five megabytes or less in size. Trying to upload a different file, or a bigger file, results in an error.

Checking your upload has worked

Producers can check the upload has been successful by:

Looking for the green tick icon – this confirms the upload has worked.
Check each term through the search function in the Terms List.

Create vocabulary terms