Languages and Translations


Languages & Translations

With these settings, you can:

  • Add a new language option for your interface
  • Export interface text for bulk translation
  • Import translations
  • Translate individual parts of the interface


When translations are enabled, the available languages will be shown on the top right of the Aspen Discovery interface and in the dropdown menu on the top right.



What Languages are Available?

With the way languages are structured in Aspen, you technically could have your catalog in any language by using a translation service or human to update the language. 

Languages that we have robust translations available of are:

  • Amharic (amh)
  • Arabic (ar)
  • Chinese (zh) - simplified
  • English (en)
  • French (fr)
  • Haitian-Creole (ht)
  • Korean (ko)
  • Pirate (ang)
  • Polish (pl)
  • Portuguese (pt)
  • Russian (ru)
  • Spanish (es)

With Aspen's Community Shared Content, translations are continually being worked on and more languages are being added.

If you do not see a language above and would like to share it with the Community to work on the translation with other libraries, reach out to the Aspen team at ByWater Solutions to add the language to our community server.


Updated 2024-03-29 km bws
Adding Languages

To set up a new Language.

Check the list of languages that are currently available in Aspen.

1. Visit Languages and Translations > Languages.

2. Define the language you'd like to set up. Below is an example of what the settings for Portuguese would look like.



  • Weight: Leave as zero.
  • Code: The language code - listed below. Aspen uses the list of Codes for the representation of names of languages published by the Library of Congress. 
  • Display Name - Native: The language name in the target language. This is how the language displays in the dropdown when selecting languages.

Here are some recommended native display names:

  • Amharic (amh) - አማርኛ
  • Arabic (ar) - العربية
  • Chinese (zh) - simplified - 中文
  • English (en) - English
  • French (fr) - Français
  • Haitian-Creole (ht) - Kreyòl ayisyen
  • Korean (ko) - 한국어
  • Polish (pl) - Polski
  • Portuguese (pt) - Português
  • Russian (ru) - Russkij
  • Spanish (es) - Español

  • Display Name - English: The language name in English. This is for staff's benefit to know which language is within the settings. This is for internal use only.

  • Locale: An identifier consisting of a language code and a country / region code, e.g. en-US. Locales may be used to define language / region specific preferences in the user interface, such as formatting for currency. See the ISO list of country codes to find the correct one.

  • Facet Value: You should put the English language version here. This correlates to connecting the user's language preferences and their search result preferences. This is teaching Aspen the connection between the user's language preference and the corresponding search facet. For example, if someone selects Español and saves, then an additional selection of - ¿Como le gustaría ver los materiales en español? appears and users can adjust their searching preferences. Aspen knows that the Spanish language translation preference = the Spanish language facet preference.



At the bottom, there is an option to display the language to translators only. Translators will need the Translate Aspen permission assigned to one of their roles. (Click here for help with users and permissions.) When this option is checked, the interface translations will not be available to the public. When the translator has completed translations to their satisfaction, return to these settings and uncheck this box so the translated interface will be available to your users.

If that language is available from the Aspen Community via Community Content Sharing, there is nothing else for you to do and the language will load. Learn more about the Community Content Sharing options.

A cron runs to load the newly added language translations. This takes an overnight process. If you need a translation added sooner, reach out to the Aspen Support Team to manually prompt the cron to run.

Updated 2024-04-17 km bws
Translation Mode

Translation mode is an easy way to start translating anything on your library page. First, make sure you have the correct language to translate. If you are not set in the correct language, use the "Languages" dropdown menu in the top right corner to change the language. Then, click "Start Translation Mode" in the top right corner.



When in translation mode, translators are able to see boxes next to translatable items that correspond to the term and the translated term. Green boxes have already been translated (but can be modified), and red boxes have not been translated yet.


Click on the label to open the "Translate a term" box.


Enter your new term/phrase in the Translation box.


To stop translating, click Exit Translation Mode in the top-right corner of the screen.


Note: You can also Start or Stop Translation Mode in Aspen Administration > Languages and Translations > Translations > Start/Stop Translation Mode.



You can view and search through all interface terms and translated terms in Aspen Administration >  Languages and Translations > Translations.


Note: Any changes to languages and translations are global per server. If you share a server with several other libraries with their own individual catalogs, translation changes will be applied to ALL libraries. 

Translations - Interface Search

While Translation Mode is great for quickly modifying text that shows up while browsing the catalog, using the Translations search allows you to view and search through all translatable terms within the Aspen interface. 


To get started, head to Aspen Administration > Languages and Translations > Translations.

By default, Aspen will show all terms. If you want to hide terms that have already been translated and focus only on untranslated terms, check Hide terms that have been translated already.

To see terms added to the interface during a certain time period, you can use the Show Terms created since calendar and narrow down by date and/or time. This does take into consideration API calls and translations in LiDA as well.

To focus on terms showing either to the public or just in Aspen administration, you have options in the Show Terms Displayed To dropdown:

  • Either Public or Administration Users
  • Only Public Users
  • Only Administration Users

Selecting Only Public Users will filter out terms in the back-end settings, so this is a great way to focus on terms visible within the public interface.

Aspen will attempt to filter out metadata terms and phrases by default. To include this data, check Show metadata (from MARC Records, eContent, etc.)

Aspen will attempt to filter out admin-entered data by default. To include this data, check Show admin entered data (list names, system messages, etc.). These terms typically include text that can be modified through settings (see list here), so any changes to the text in English should ideally be done from the settings (instead of translating them) to prevent confusion.

To search for a term to translate, enter the term or phrase in Show Terms Containing.

To search for a term that has already been translated, enter the term or phrase in Show Translations Containing.

Note: Any changes to languages and translations are global per server. If you share a server with several other libraries with their own individual catalogs, translation changes will be applied to ALL libraries. 


Updated 2024-07-16 md bws
Importing/Exporting Translations

Why would you want to import and export languages? 

You would want to import languages if you are setting up a whole new language within Aspen that is not currently available from the Aspen Community Sharing Languages. Or, if you have done extensive translation work on an existing language and you would like to update your existing translations in Aspen.

Import and Export Languages

In Aspen Administration > Languages & Translations > Translations you can click Import Translations or Import Bulk Translations to import any new or updated languages.


For exporting translations, follow the same steps, but choose one of the exporting options. If you already have some translations in place for the language and do not wish to replace those specific ones, leave the box next to "Overwrite Existing Translations?" unchecked.


Export All Translations - This will download a CSV file where languages will be separated out by column. The first column contains the interface term, and subsequent columns are for the language translations. Each column has a header containing the language code. If you set these languages up prior to exporting translations (click here for instructions on setting up a new language), the column headers will be added to the spreadsheet for you automatically.



If your Aspen site is live and you wish to add a new language, you may want to click Display to Translators Only in that language' settings while actively working on that language.

When you are ready to import your translations, return to this section and click Import Translations. Select the language translations you'd like to import.



Export For Bulk Translation - This will download a txt file of all the interface terms used in Aspen, which you can then run through a translation tool such as Google Translate. When you are finished, upload the translated file via Import Bulk Translations.

Important - make sure your current interface translation matches the language of the translation you are importing. For example, if you are uploading a Russian translation, make sure you are currently have the Russian interface active.


2023-04-19 km bws
Hide Translations While Working on a Language

If you are actively working on a translation and do not want it to show publicly to patrons yet, you can go to Aspen Administration > Languages and Translations > Languages > select the language you are working on > check Display To Translators Only.

Once checked, regular users won't see this language as an option to select for the interface translation. When you're ready for the translation to be available to everyone, return to these settings and uncheck Display to Translators Only. 


Translating Results Within Facets using Translation Maps vs. Translation Mode

Updating Facets with a Translation Map

Aspen has Translation maps for data such as audience, collection, itype, literary_form, location (as in the physical branch), shelf_location, sub_location and target_audience.

The subfields connected to these fields are defined in ILS ILS Integration > Indexing Profiles > click into your settings > Item Information. For example, the shelf_location Translation Map will be looking at information stored in the item record subfield c in this screenshot.


If you are wanting to make changes to those facets and the way this information displays in records, you can do this from one of Aspen's Translation Maps.

The Translation Maps are located in ILS Integration > Translation Maps > click into the specific map.

You can also get to these from ILS Integration > Indexing Profiles > click into your settings > scroll all the way to the bottom under Translation Maps and click edit on the map you want to access.

Below is an example of the shelf_location Translation Map.

Information in the Value column is the code that Aspen is reading from the ILS and cannot be edited/changed. 

Information in the Translation column is what Aspen displays in the catalog and is what can be changed.

For example, your shelf location value is 'HALL' but you want this to display to patrons as 'Long Hall'. 

If you want to download this table, you can click Download as INI at the top.

You can also click View as INI.

If a table is blank or a new, full data set needs to be uploaded, you can click Load From CSV/INI. Typically, this is either done automatically via your ILS connection (Koha, Polaris) or uploaded manually by your Implementation Specialist during implementation. 

Changes made in your ILS to these value translations do not automatically change how they display in Aspen. Changes will also need to be made in the Translation Maps in Aspen for these changes to go into effect.

Changes to the Translation column take an overnight index. You can click into an example record you are trying to change, go to the Staff View > click Force Reindex to see display changes within a 15 minute window.

Translation values are limited to 255 characters. 

Regular expressions can be used by clicking on Use Regular Expressions to map a number of different Value codes to the same Translations. Exp. All of your values that begin with J should map to Juvenile Fiction.

Making changes to this table has the potential to break any exisitng browse categories that are using these values as a facet. See more information here on how to fix this.


Translate Facets that Don't have a Translation Map

The most common use for this is the eConent facet to translate OverDrive to Libby or OverDrive/Libby.

Translating the results within the facets are OFF by default in translation mode. For facets, such as Subject, there are thousdands of words that may never need to be translated so we keep this off for speed and performance.

To turn translation on for specific facet results (example: Changing OverDrive to Libby), go to Catalog/Grouped Works > Grouped Work Facets > edit the facet setting.  Navigate to the facet that you want to translate within and check the box for "Translate?"



Once you return to the search results, open up the search facet and click Start Translation Mode in the top-right corner of the screen. You will now be able to translate the options within the facet(s).


Note: If you have multiple Grouped Work Facets settings attached to different catalogs, and you'd like the same facets translatable for all of them, you must repeat this process for all applicable Grouped Work Facets settings. 


Updated 2023-09-22 km bws
What can be changed with Settings vs. Translation Mode?

Translation Mode and the Translation search tool are a great way to customize parts of your Aspen interface. With so many options, we wanted to list out parts of the interface that can easily be changed within Aspen settings rather than resorting to using Translation tools.


Format Labels: Change these in ILS Integration > Indexing Profiles > Format Information. Edit the value in the Format column to change the format label in the catalog. 

Status Labels: Change these in ILS Integration > Indexing Profiles > Status Mappings. Edit the value in the Status column to change the status label in the catalog. 

Sign-in Labels: Change these in Primary Configuration > Library Systems > ILS/Account Integration > Login > Login Form Username Label and Login Form Password Label.

Facet Labels: Change these in Catalog/Grouped Works > Grouped Work Facets > edit the setting. Edit the value in the Display Name fields to change the facet label.

Home and Browse Links: In Theme & Layout > Layout > "Where to use custom Home Link from Library Settings" -- if you are using an option that enables the Breadcrumbs and Menu links, you can change the breadcrumb/menu link text here.

Account Expiration Near / Account Expired Messages: In Primary Configuration > Library Systems > ILS/Account Integration, if you have "Show Expiration Warnings" checked, you can configure those messages in the Expiration Near Message and Expired Message fields.

Holds Disclaimer Message: This optional message will display within the holds screen when a user places a hold. This can be configured/edited in Primary Configuration > Library Systems > ILS/Account Integration > Holds > Hold Disclaimer.

Self Registration Form Message / Success Message: Can change these in Primary Configuration > Library Systems > ILS/Account Integration > Self Registration. 

Materials Request New Request Summary: Can change this in Primary Configuration > Library Systems > Materials Request > New Request Summary. This is the message that displays above the materials request form when using the Koha ILS request system or Aspen's request system.

Library Hours / Holiday message in User Account: The message that displays in user accounts on the Checked Out Titles and Titles On Hold screens can be enabled or disabled in Primary Configuration > Library Systems > ILS/Account Integration > "Show Library Hours Notice on Account Pages."

The hours and holiday information that displays here pulls from the hours set up in Location settings and the Holidays set up in Library Systems settings. If the placeholder variables for the library/hours/holiday are edited out of the text via Translation tools, this will break the display of this message.


2023-04-17 md bws
Link to a Specific Language Translation

To link to a specific area of Aspen in a certain language translation, add this convention to the end of a URL:

?myLang={Language Code}

Example: /MyAccount/Home?myLang=es

Note: This language code must match one of the Language translations you have added to your Aspen catalog.

This will link directly to that section of Aspen in that specific language:

User Experience

Whether or not users have the ability to control language options from the header is controlled by the setting found in:

Aspen Administration > Primary Configuration > Library Systems > click into Library System > Basic Display > Show Language and Display Settings in Page Header

Select a Language from the Header When Logged In

When a user is logged into Aspen and clicks on the Languages or Languages & Display button in your header, it will take the user into My Account > My Preferences.

If you have multiple language translations available in your Aspen catalog, users can choose a language for browsing Aspen. Once they select a language and save, the user will see an additional menu of options pop up: "Do you want to prefer materials in English?" The options for users are:

  • No, show interfiled with other languages
  • Yes, show above other languages
  • Yes, only show my preferred language

Note: The menu options in the dropdown menu do not automatically translate to the selected language. You can translate these options by either entering translation mode or going into the Translations section of Aspen.


Select a Language from the Header When Not Logged In

When users are not logged in and browsing Aspen, they will see a Languages or Languages & Display option in the top-right corner of your header.

When a user clicks on this, they will be presented with any of the languages you have set up on your Aspen server.

Once they select a language and click Update Settings, Aspen's interface elements will switch to displaying in that language.

Select a Language from the Hamburger Menu

Users can select menus from the hamburger side menu and automatically be switched into that language translation in one click whether than logged in or not.