This documentation relates to an old version of VIVO, version 1.10.x. Looking for another version? See all documentation.
VIVO Language Support
When a VIVO site supports a language other than English, that support includes:
- Text that is displayed in the VIVO pages. For example, menus, selections, prompts, tool-tips and plain text.
- Text from terms in the Ontology, which are frequently displayed as links or section headings. Text includes labels and annotations of properties and classes.
- Text values stored in the data. For example, if a book title is available in both French and English, a French-speaking user sees the French title. If a title is available only in English, it is displayed, without regard to the user's preference in languages.
Languages can be selected in a variety of ways, depending on the installation parameters:
- A VIVO installer can configure VIVO to use one of the supported languages.
- Different users may see different languages, depending on the settings in their web browser.
- Different users may select a language from a list of available languages.
VIVO language files are available for English, Spanish, Brazilian Portuguese, and German. If you need support for another language, please inquire of the VIVO mailing lists, to see if another group has the files you need.
Adding an existing language to your VIVO site
In this step by step guide we will use the German language files as an example. After you installed VIVO (as described here), clone your desired
Vitro-language folders/repositories (in this example we will use the files from https://github.com/vivo-DE). Be sure to use the theme 'wilma' or 'tenderfoot' for this to work without issues.
- Go into each language folder (
VIVO-languageand Vitro-language) and install them with Maven using
Go into the VIVO project folder and uncomment the section for multiple language support (search for '
<!-- Dependencies for multilingual support -->'
<!-- Overlays for multilingual support -->' inside of the files) in each of the
pom.xmlfiles listed below:
- Vitro/installer/webapp/pom.xml (Uncomment dependencies and overlays)
VIVO/installer/home/pom.xml (Uncomment dependencies)
VIVO/installer/webapp/pom.xml(Uncomment dependencies and overlays)
<version>in the two
pom.xmlfiles to the same version as in the '
VIVO-language/pom.xml' and '
Vitro-language/pom.xml' file respectively. You may need to change the version in multiple places in the files.
- Build VIVO from the VIVO project folder using
mvn install -s installer/my-settings.xml
- Edit the
vivo_home_dir/config/runtime.propertiesfile in your VIVO home directory:
RDFService.languageFilter = true
languages.selectableLocales = en_US, de_DE
- Restart the tomcat
- You should now be able to select your installed language (in this case German) in the header of your VIVO site
Creating new language files for your language
First, contact the VIVO development team. We would love to talk to you. We will be happy to help with any questions you may have and introduce you to others who may be working on the same language as you are.
When your files are ready, you can make them available to the development team in any way you choose. Note that the VIVO project will release your files under the Apache 2 License. They will require a Contributor Agreement stating that you agree to the terms in the agreement.
Translating VIVO into your language involves determining a locale, and preparing files as discussed below.
Your locale is an internationally recognized code that specifies the language you choose, and the region where it is spoken. For example, the locale string
fr_CA is used for French as spoken in Canada, and
es_MX is used for Spanish as spoken in Mexico. Recognized codes for languages and regions can be found by a simple Google search. Here is a list of locales that are recognized by the Java programming language. You may also use this definitive list of languages and regions, maintained by the Internet Assigned Numbers Authority.
The locale code will appear in the name of each file that you create. In the files that contain RDF data, the locale code will also appear at the end of each line.
When the locale code appears in file names, it contains an underscore
(en_US). When it appears inside RDF data files, it contains a hyphen (
The language files
You can get the US English (en_US) files from the VIVO-language and Vitro-language among the vivo-project repositories(https://github.com/vivo-project), to use as a template for your own files.
The process simply consist of duplicating each file having the extension en_US inside VIVO/Vitro -language repositories and renaming the copy using the locale of the new language. The new file will reside along side (in the same directory) the original one.
For example, when initializing the languages files for Estonian(
et_EE), copying the file vivo_all_en_US.properties will help creating vivo_all_et_EE.properties. Both of them will reside in vivo-languages/webapp/src/main/webapp/i18n
In the process of initializing the files for a new language. You will encounter the following types of file:
Text strings (.properties)
These files contain about 1500 words and phrases that appear in the VIVO/Vitro web pages.
These words and phrases have been removed from the page templates, so no programming knowledge is required to translate them.
They appear at different level in the application :
- in Vitro-languages/webapp/src/main/webapp/i18n
- in VIVO-languages/webapp/src/main/webapp/i18n
- in each theme's i18n directory. For instance :
- VIVO-languages/webapp/src/main/webapp/themes/tenderfoot/i18n and
The application will look for an entry starting with the activated theme(like tenderfoot or wilma), then VIVO and lastly Vitro.
Freemarker Templates (.ftl)
Almost all of the text in the Freemarker templates is supplied by the text strings in the properties files. However, some Freemarker templates are essentially all text, and it seemed simpler to create a translation of the entire template. These include the
about pages, the
They are located in:
Here are some examples of templates files to create for Estonian support
RDF data (.n3, .nt)
Data in the RDF models includes labels for the properties and classes, labels for property groups and class groups, labels for menu pages and more. Here is the list of directories where one will have to create required rdf files:
In each case, the delivered file in English has a corresponding file with the same name followed by and underscore and the name of the locale. See illustrations below:
In each file, labels specify text to be used by VIVO. Each label should be translated and affixed with the appropriate locale tag. See below:
The selection image (.png, .jpeg, .gif)
If you allow the user to select a preferred language, you must supply an image for the user to click on. Typically, this image is of the flag of the country(or the language) where the language is spoken.
Here are the locations you need to add the flag of the language:
You need to add the image to the themes you will be using. Here the path to the image that will load with wilma:
How VIVO supports languages
Language in the data model
The usual form of language support in RDF is to include multiple labels for a single individual, each with a language specifier.
In fact, any set of triples in the data model are considered to be equivalent if they differ only in that the objects are strings with different language specifiers. If language filtering is enabled, VIVO will display the value that matches the user's preferred locale. If no value exactly matches the locale, the closest match is displayed.
Consider these triples in the data:
VIVO would display these values as follows:
|User's preferred locale||displayed text|
VIVO has limited language support for editing values in the GUI. It is possible to edit language-specific labels for individuals. Language-specific values for other properties must be ingested into VIVO.
Language support in VIVO pages
In the I18n framework, displayed text strings are not embedded in the Java classes or in the Freemarker template. Instead, each piece of text is assigned a "key" and the code will ask the framework to provide the text string that is associated with that key. The framework has access to sets of properties files, one set for each supported language, and it will use the appropriate set to get the correct strings.
For example, suppose that we have:
- The text that will appear in an HTML link, used to cancel the current operation, with the key
- The title of a page used to upload an image, with the key
- The text of a prompt message, telling users how big an image must be, with the key
The default properties file might show the English language versions of these properties, like this:
Notice that the actual image dimensions are not part of the text string. Instead, placeholders are used to show where the dimensions will appear when they are supplied. This allows us to specify the language-dependent parts of a message in the properties file, while waiting to specify the language-independent parts at run time.
A Spanish language properties file might show the Spanish versions of these properties in a similar manner:
To use these strings in Java code, start with the I18n class, and the key to the string. Supply values as needed to replace any placeholders in the message.
Similarly, using text strings in a Freemarker template begins with the
Here is the appearance of the page in question, in English and in Spanish:
Structure of the properties files
The properties files that hold text strings are based on the Java I18n framework for resource bundles. Here is a tutorial on resource bundles.
Most text strings will be simple, as shown previously. However, the syntax for expressing text strings is very powerful, and can become complex. As an example, take this text string that handles both singular and plural:
Local extension: application vs. theme
The Java I18n framework expects all properties files to be in one location. In VIVO, this has been extended to look in two locations for text strings. First, it looks for properties files in the current theme directory. Then, it looks in the main application area. This means that you don't need to include all of the basic text strings in your theme. But you can still add or override strings in your theme.
If your VIVO theme is named "frodo", then your text strings (using the default bundle name) would be in
If you specify more than one locale for VIVO, this search pattern becomes longer. For example, if your user has chosen Canadian French as his language/country combination, then these files (if they exist) will be searched for text strings:
When VIVO finds a text string in one of these files, it uses that value, and will not search the remaining files.
Language in Freemarker page templates
Here is some example code from
This code lays out all of the formatting and markup, but the actual strings of text are retrieved from the property files, depending on the current language and locale. Here are the English-language strings used by this code:
Most Freemaker templates are constructed like the one above; the text is merged with the markup at runtime. In most cases, this results in lower maintenance efforts, since the markup can be re-structured without affecting the text that is displayed.
In some cases, however, the template is predominantly made up of text, with very little markup. In these cases, it is simpler to rewrite the entire template in the chosen language.
The Freemarker framework has anticipated this. When a template is requested, Freemarker will first look for a language-specific version of the template that matches the current locale. So, if the current locale is
es_MX, and a request is made for
termsOfUse.ftl, Freemarker will look for these template files:
Search order for
Current locale is
Language in Java code
Java code has access to the same language properties that Freemarker accesses. Here is an example of using a language-specific string in Java code:
The properties files contain this line:
Note how the name of the VIVO site is passed as a parameter to the text message.
Language in JSPs
Up through VIVO release 1.10, no attempt has been made to add language support to JSPs.
For example, the template can contain this:
And the script can contain this:
i18nChecker is a set of Ruby scripts that are distributed with VIVO, in the
utilities/languageSupport/i18nChecker directory. Use them to scan your language properties files and your freemarker templates. The scripts look for common errors in the files.
Scanning language properties files
- Warn if a specialized file has no default version.
- Warn about duplicate keys, keys with empty values.
- Warn about keys that do not appear in the default version.
- If the "complete" flag is set,
- Warn if the default version is not found.
- Warn about missing keys, compared to the default version.
Scanning Freemarker templates
- Warn about visible text that contains other than blank space or Freemarker expressions.
- Visible text is:
- Anything that is not inside a tag and not between <script> tags
- title="" attributes on any tags
- alert="" attributes on <img> tags
- alt="" attributes on <img> tags
- value="" attributes on <input> tags with submit attributes