Versions Compared

Old Version 5

changes.mady.by.user Manuel Schwarz

Saved on

compared with

New Version Current

changes.mady.by.user Kitio Fofack

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

VIVO Language Support

Multiple language support can mean many things. 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.
  • Terms Text from terms in the Ontology, which are frequently displayed as links or section headings.Labels and descriptions   Text includes labels and annotations of properties and classes.
  • Text values stored in the data model.
    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.

Language support in VIVO is being implemented in phases:

  • Phase 1 includes read-only support of public pages:
    • Pages that are visible to users who are not logged in.
    • Also includes support of some administrative pages.
    • This is currently available.
  • Phase 2 will also provide read-write support of profile pages:
    • Users will be able to edit language-specific data in profile pages.
  • Phase 3 will support administrative pages
    • Creating user accounts, manipulating RDF data and other administrative functions.
  • Phase 4 will support "back-end" pages.
    • Used to edit the ontology, or to do low-level editing on individual entities.

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 is already developing the files you need.

Adding a language to your VIVO site

Adding language files to VIVO

VIVO is distributed with English as the only supported language. VIVO also includes a set of "pseudo-language" files, as a demonstration of how language support is implemented.

Additional language files are available in the Git repositories at https://github.com/vivo-project/Vitro-languages and https://github.com/vivo-project/VIVO-languages.

If the repository contains files for the language you want, in the VIVO release that you are using, you can just download those files and install them as shown below.

How to install language files 

In this step by step guide we will use the German language files as an example. After you installed VIVO like described here, get your desired VIVO-language and Vitro-language folders/repositories

(in this example we will use the files found at https://github.com/vivo-DE).

  • go into each language folder (VIVO-language and Vitro-language) and 'install' them with Maven ("mvn install")

  • next, go into the VIVO project folder and uncomment the section for multiple language support in the two pom.xml files listed below:
    (search for '<!-- Dependencies for multilingual support -->' inside of the files)

    1. VIVO/installer/home/pom.xml
    2. VIVO/installer/webapp/pom.xml
    Make sure to change the <version> in the pom.xml-files to the same version as in the VIVO-/Vitro-language/pom.xml files.
    In this example we had to change <version>[2.0.0,2.1.0)</version> to <version>2.0.0-SNAPSHOT</version>.
    (Note that these should be the home/pom.xml and webapp/pom.xml in whatever installer project is being used to deploy VIVO.)
  • after that, we have to build VIVO again, so go into the VIVO project folder and
    • "mvn install -s installer/my-settings.xml"
  • now edit the 'runtime.properties' file in your VIVO home directory (e.g. '/vivo/home/config/')
    • uncomment/add 'RDFService.languageFilter = true'
    • uncomment/add 'languages.selectableLocales = en_US, de_DE'
  • for the menu to be displayed correctly in German, you have to rename the file 'menu_de_DE.nt' to 'menu_de_DE.n3'
    in the directory /vivo_home_dir/rdf/display/everytime/ (This next step might not be necessary in the future)
  • restart the tomcat
  • you should now be able to select your installed language (in this case German) in the header of your VIVO site

Translating VIVO into your language

First, contact the VIVO development team: we would love to talk to you. We will tell you if anyone else is working on your language, and we will be happy to help with any questions you may have.

When you are ready to go ahead, you must determine the "locale" of your translation. Then you prepare translations of twenty-one files, as shown below.

The locale

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.

Note

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 (en-US).

The language files

You can get the Spanish or the English files from the VIVO and Vitro language repositories, to use as a template for your own files.

The example that follow assume that you are creating files for the Estonian language, as spoken in Estonia, with the locale et_EE.

Text strings (.properties)

These files contain about 1500 words and phrases that appear in the VIVO web pages. The page templates contain more than just text – they contain programming logic and display specifiers.

These words and phrases have been removed from the page templates, so no programming knowledge is required to translate them.

There is one file for phrases used in Vitro, the core around which VIVO is built, and one file for phrases that are specific to VIVO. In the example, these two files are both called all_et_EE.properties.

Code Block
titleExample file names
[Vitro]/webapp/languages/et_EE/i18n/all_et_EE.properties
[VIVO]/languages/et_EE/themes/wilma/i18n/all_et_EE.properties
Code Block
titleExample content
minimum_image_dimensions = Minimaalne pildi mõõdud: {0} x {1} pikslit 
cropping_caption = Profiilifoto näeb alloleval pildil.

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 help and about pages, the Terms of Use page, and the emails that are sent to new VIVO users.

Code Block
titleExample file names
[Vitro]/webapp/languages/et_EE/templates/freemarker/search-help_et_EE.ftl
[Vitro]/webapp/languages/et_EE/templates/freemarker/termsOfUse_et_EE.ftl
[Vitro]/webapp/languages/et_EE/templates/freemarker/userAccounts-acctCreatedEmail_et_EE.ftl
[Vitro]/webapp/languages/et_EE/templates/freemarker/userAccounts-acctCreatedExternalOnlyEmail_et_EE.ftl
[Vitro]/webapp/languages/et_EE/templates/freemarker/userAccounts-confirmEmailChangedEmail_et_EE.ftl
[Vitro]/webapp/languages/et_EE/templates/freemarker/userAccounts-firstTimeExternalEmail_et_EE.ftl
[Vitro]/webapp/languages/et_EE/templates/freemarker/userAccounts-passwordCreatedEmail_et_EE.ftl
[Vitro]/webapp/languages/et_EE/templates/freemarker/userAccounts-passwordResetCompleteEmail_et_EE.ftl
[Vitro]/webapp/languages/et_EE/templates/freemarker/userAccounts-passwordResetPendingEmail_et_EE.ftl
[VIVO]/languages/et_EE/templates/freemarker/aboutMapOfScience_et_EE.ftl
[VIVO]/languages/et_EE/templates/freemarker/aboutQrCodes_et_EE.ftl
[VIVO]/languages/et_EE/templates/freemarker/mapOfScienceTooltips_et_EE.ftl

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 VIVO-language and 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-language and Vitro-language) and install them with Maven using mvn install

  • Go into the VIVO project folder and uncomment the section for multiple language support (search for '<!-- Dependencies for multilingual support -->' and '<!-- Overlays for multilingual support -->' inside of the files)  in each of the pom.xml files 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)
    Change the <version> in the two pom.xml files 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.properties file in your VIVO home directory:
    • uncomment/add RDFService.languageFilter = true
    • uncomment/add 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.

The locale

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.

Note

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 (en-US).

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
    • VIVO-languages/webapp/src/main/webapp/themes/wilma/i18n

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 help and about pages, the Terms of Use page, and the emails that are sent to new VIVO users.

They are located in:

  • Vitro-languages/webapp/src/main/webapp/templates/freemarker
  • VIVO-languages/webapp/src/main/webapp/templates/freemarker/body
  • VIVO-languages/webapp/src/main/webapp/templates/freemarker/visualization/capabilitymap
  • VIVO-languages/webapp/src/main/webapp/templates/freemarker/visualization/mapOfScience

Here are some examples of templates files to create for Estonian support

Code Block
titleExample file names
Vitro-languages/webapp/src/main/webapp/templates/freemarker/search-help_et_EE.ftl
Vitro-languages/webapp/src/main/webapp/templates/freemarker/termsOfUse_et_EE.ftl
Vitro-languages/webapp/src/main/webapp/templates/freemarker/userAccounts-acctCreatedEmail_et_EE.ftl
Vitro-languages/webapp/src/main/webapp/templates/freemarker/userAccounts-acctCreatedExternalOnlyEmail_et_EE.ftl
Vitro-languages/webapp/src/main/webapp/templates/freemarker/userAccounts-confirmEmailChangedEmail_et_EE.ftl
Vitro-languages/webapp/src/main/webapp/templates/freemarker/userAccounts-firstTimeExternalEmail_et_EE.ftl
Vitro-languages/webapp/src/main/webapp/templates/freemarker/userAccounts-passwordCreatedEmail_et_EE.ftl
Vitro-languages/webapp/src/main/webapp/templates/freemarker/userAccounts-passwordResetCompleteEmail_et_EE.ftl
Vitro-languages/webapp/src/main/webapp/templates/freemarker/userAccounts-passwordResetPendingEmail_et_EE.ftl
VIVO-languages/webapp/src/main/webapp/templates/freemarker/body/aboutMapOfScience_et_EE.ftl
VIVO-languages/webapp/src/main/webapp/templates/freemarker/body/aboutQrCodes_et_EE.ftl
VIVO-languages/webapp/src/main/webapp/templates/freemarker/visualization/mapOfScience/mapOfScienceTooltips_et_EE.ftl


Code Block
titleTerms of Use (Estonian)
<section id="terms" role="region">
    <h2>kasutustingimused</h2> 
    
    <h3>Hoiatused</h3> 

    <p>
        See ${termsOfUse.siteName} veebisait sisaldab materjali; teksti informatsiooni 
        avaldamine tsitaadid, viited ja pildid ikka teie poolt ${termsOfUse.siteHost} 
        ja erinevate kolmandatele isikutele, nii üksikisikute ja organisatsioonide, 
        äri-ja muidu. Sel määral copyrightable Siin esitatud infot VIVO veebilehel ja 
        kättesaadavaks Resource Description Framework (RDF) andmed alates VIVO at 
        ${termsOfUse.siteHost} on mõeldud avalikuks kasutamiseks ja vaba levitamise 
        tingimuste kohaselt 
        <a href="http://creativecommons.org/licenses/by/3.0/" 
                target="_blank" title="creative commons">
            Creative Commons CC-BY 3.0
        </a>
Code Block
titleExample content
<section id="terms" role="region">
    <h2>kasutustingimused</h2> 
    
    <h3>Hoiatused</h3> 

    <p>
        See ${termsOfUse.siteName} veebisait sisaldab materjali; teksti informatsiooni 
        avaldamine tsitaadid, viited ja pildid ikka teie poolt ${termsOfUse.siteHost} 
        ja erinevate kolmandatele isikutele, nii üksikisikute ja organisatsioonide, 
        äri-ja muidu. Sel määral copyrightable Siin esitatud infot VIVO veebilehel ja 
        kättesaadavaks Resource Description Framework (RDF) andmed alates VIVO at 
        ${termsOfUse.siteHost} on mõeldud avalikuks kasutamiseks ja vaba levitamise 
        tingimuste kohaselt 
        <a href="http://creativecommons.org/licenses/by/3.0/" 
                target="_blank" title="creative commons">litsentsi, mis võimaldab teil kopeerida, levitada, kuvada ja muuta derivaadid 
        seda teavet teile anda Creative Commons CC-BY 3.0laenu ${termsOfUse.siteHost}.  
        </a> 
        litsentsi, mis võimaldab teil kopeerida, levitada, kuvada ja muuta derivaadid 
        seda teavet teile anda laenu ${termsOfUse.siteHost}.  
    </p>
</section>

RDF data (.n3)

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.

p>
</section>

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:

  • VIVO-languages/home/src/main/resources/rdf/applicationMetadata/everytime
  • VIVO-languages/home/src/main/resources/rdf/display/everytime
  • VIVO-languages/home/src/main/resources/rdf/display/firsttime
  • VIVO-languages/home/src/main/resources/rdf/tbox/everytime

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:

Code Block
titleFile names (Estonian)
Code Block
titleExample file names
[VIVO]/languages/et_EE/rdf/applicationMetadata/firsttime/classgroups_labels_et_EE.n3
[VIVO]/languages/et_EE/rdf/applicationMetadata/firsttime/propertygroups_labels_et_EE.n3
[VIVO]/languages/et_EE/rdf/display/everytime/PropertyConfig_et_EE.n3
[VIVO]/languages/et_EE/rdf/display/firsttime/aboutPage_et_EE.n3
[VIVO]/languages/et_EE/rdf/display/firsttime/menu_et_EE.n3
[VIVO]/languages/et_EE/rdf/tbox/firsttime/initialTBoxAnnotations_et_EE.n3vitroAnnotations_et_EE.n3

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:

Code Block
titleExample contentSome classgroups_labels (Estonian)
<http://vivoweb.org/ontology#vitroClassGrouppeople> 
    <http://www.w3.org/2000/01/rdf-schema#label> "inimesed"@et-EE .
<http://vivoweb.org/ontology#vitroClassGrouppublications> 
    <http://www.w3.org/2000/01/rdf-schema#label> "teadus"@et-EE .
<http://vivoweb.org/ontology#vitroClassGrouporganizations> 
    <http://www.w3.org/2000/01/rdf-schema#label> "organisatsioonid"@et-EE .
<http://vivoweb.org/ontology#vitroClassGroupactivities> 
    <http://www.w3.org/2000/01/rdf-schema#label> "tegevused"@et-EE .

...

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.

...

titleExample file names

...

Here are the locations you need to add the flag of the language:

  • Vitro-languages/webapp/src/main/webapp/themes/vitro/i18n/images
  • VIVO-languages/webapp/src/main/webapp/themes/tenderfoot/i18n/images
  • VIVO-languages/webapp/src/main/webapp/themes/wilma/i18n/images

...

You need to add the image to the themes you will be using. Here the path to the image that will load with wilma:

Code Block
titleSelect Local Image File name (Estonian)
VIVO-languages/webapp/src/main/webapp/themes/wilma/i18n/images/select_locale_et_EE.gif


Panel
titleImage for locale selection (Estonian)

Image Added

How VIVO supports languages

Panel
titleExample content

Image Removed

How can I contribute my language files to the VIVO community?

If you are planning to create a translation of VIVO, you should coordinate with the VIVO developers. 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 those terms.

Adding language support to your local modifications

...

Language in the data model

...

Note

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

This section deals with the framework of the VIVO pages: the page titles, the prompts, the tool tips, the error messages; everything that doesn't come from the data model. These pieces of text are not stored in RDF, so we need a different mechanism for managing them.

specific values for other properties must be ingested into VIVO.

Language support in VIVO pages

VIVO uses The mechanism we use is based on the Java language's built-in framework for Internationalization. You can find more information in the Java tutorials for resource bundles and properties files.

...

 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 codekey. 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.

...

Code Block
titleUsing I18n strings from Java code
protected String getTitle(String siteName, VitroRequest vreq) {
    return I18n.text(vreq, "upload_image_page_title");
}

private String getPrompt(HttpServletRequest req, int width, int height) {
    return I18n.text(req, "minimum_image_dimensions", width, height);
}

...

The text strings are processed by the Java I18n framework for message formats. Here is a tutorial on message formats. Full details can be found in the description of the MessageFormat class.

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.

...

  • webapp/themes/frodo/i18n/all.properties
  • webapp/i18n/all.properties

If you specify a complex 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:

...

Code Block
titleEnglish properties used in the example
intro_searchvivo = Search VIVO
search_form = Search form
search_button = Search
intro_filtersearch = Filter search
all_capitalized = All

Language-specific templates

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.

...

Up through VIVO release 1.710, no attempt has been made to add language support to JSPs.

Language in JavaScript files

There is no convenient way to access the i18n framework from JavaScript files. One workaround is to assign values to JavaScript To access string properties in JavaScript called from a template, assign the properties to variables in the Freemarker template, and then access those values from the JavaScript.

...

Code Block
titleExcerpt from homePageMaps.js
        if ( area == "global" ) {
            text = " " + i18nStrings.countriesAndRegions;
        }
        else if ( area == "country" ) {
            text = " " + i18nStrings.statesString;
        }

...

i18nChecker

i18nChecker

...

This 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

...