Localizing the End-user Interface

CONTENTdm provides features to localize and customize the text used for website navigation, interface element labels (e.g., the Search button), site and collection descriptions, and messages like confirmations and errors.

You can edit most of the interface text at the global and collection levels by editing the appropriate XML files:

  • For the entire Website (global) changes, edit cdm_language.xml
  • For collection-level changes, edit cdm_language_coll_{collection alias}.xml

In addition, some interface text can be edited directly by using the Website Configuration Tool (e.g. header, footer, descriptions).

Note: If you are having problems displaying Unicode characters in your browser, in the Website Configuration Tool > Appearance > Text option, set the Font-Family drop-down for all options to Arial Unicode MS to fix the issue.

Learn About:

 

Localizing the Header, Footer & Descriptions in a Single Language

If you need to localize your Website for only one language, the global-level and collection-level header, footer, and descriptions can be edited directly by using the Website Configuration Tool.

To localize or customize the website header

To localize or customize the website footer

Edit the website footer links by using Website Configuration Tool > Navigation > Footer option.

To localize or customize descriptions

Localizing the Website Interface Text

The website "interface text" refers to the text that cannot be directly edited in the Website Configuration Tool. This text can be localized in one or more languages in the cdm_language.xml file. It is a UTF-8 encoded XML file that follows the Translation Memory eXchange (TMX) standard, a popular format for translators and translation applications.

OCLC provides translations for the following languages. These translations are included in CONTENTdm installation and do not require a separate download. You can view a demo site of these languages at http://global.contentdm.oclc.org.

  • Catalan (language code = "ca")
  • Chinese – Simplified (language code = "zh_CN")
  • Chinese – Traditional (language code = "zh_TW")
  • Dutch (language code = "nl")
  • English (language code = "en_US")
  • French (language code = "fr")
  • German (language code = "de")
  • Japanese (language code = "ja")
  • Korean (language code = "kr")
  • Spanish (language code = "es")
  • Thai (language code = "th")

Note: If you want to support multiple languages or want to change the default language, the Website Configuration Tool enables you to configure the following localization-related settings:

  • Enable the end-user language selection option in the header of the website
  • Select available site languages
  • Set the default site language or default collection language

 

Localizing the Website Configuration Tool Text in Multiple Languages

If you have enabled the language selection drop-down list in the Website and are localizing into multiple languages, you can localize the text at the global level as well as the collection levels. As part of the upgrade to the Zend_Translate framework in 6.1.3, the text strings that can be directly edited within the Website Configuration Tool have corresponding multilingual translations in TMX language files. There are two new types of TMX files (in addition to the cdm_language.xml file described above):

  • cdm_language_configs.xml corresponds to all text that can be edited on the Global tab of the Website Configuration Tool
  • cdm_language_coll_{collection alias}.xml corresponds to all text that can be edited for each collection on the Collections tab of the Website Configuration Tool

These XML/TMX files can be downloaded and uploaded on the Website Configuration Tool > Tools > Language pages on the Global and Collections tabs. For example, at the collection level, the TMX file that contains the localizations for the OCLC Sample Collection is named cdm_language_coll_oclcsample.xml. For each collection and for the global level, you may localize strings into multiple languages by modifying and uploading new copies of these TMX files. If you wish to add a language that is not present in the default TMX files, you will need to add keys and language codes to cdm_language.xml, cdm_language_configs.xml, and to cdm_language_coll_{collection alias}.xml for each collection on your Server.

To download the language file for editing

You can download your current Website language files on the Website Configuration Tool > Tools > Language pages. There are three different types of files:

  • Global "interface text" strings are found in cdm_language.xml on the "Global Settings" tab.
  • Global Website Configuration Tool strings are found in cdm_language_configs.xml on the "Global Settings" tab.
  • Collection Website Configuration Tool strings are found in cdm_language_coll_{collection alias}.xml on the "Collections" tab.

After downloading and modifying the file you can upload it on the same Tools > Language page you downloaded from. Save and publish to see your changes.

Editing the Languages Files

This topic details the procedures for localizing or customizing the languages file:

  1. Downloading the file
  2. Editing using Microsoft Excel and/or the Olifant TMX editor
  3. Merging changes using Olifant (optional)
  4. Uploading the file to your website

CONTENTdm makes use of the industry standard TMX format for localizaion files. Using a TMX editor, you can add additional languages, edit the default text, and edit text strings in multiple languages. Always remember to make a backup copy of the original TMX file before changing and uploading a new file.

Any XML editor can be used to edit the TMX files. A TMX-specific editor is less error-prone and provides editing features particularly useful for localization. OCLC recommends using Olifant, an open-source Windows application. If you are using Olifant, there are some specific procedures that must be followed to guarantee that your TMX files will function properly in CONTENTdm. These precautions are a result of incorporating Zend_Translate into CONTENTdm 6.1.3. These procedures are described below.

For details on language code handling, particularly if you plan to add your own language, please consult the Zend documentation at http://framework.zend.com/manual/1.11/en/zend.translate.additional.html#zend.translate.additional.languages.

Important Note: TMX editors will allow you to delete keys, but we do not advise doing so with CONTENTdm's TMX files. Unused keys and language codes will be ignored by the CONTENTdm Website and the empty keys should be left in the TMX files to ensure future compatibility.

Following is an example from cdm_language.xml (the element indicates a translation unit):

 

Each string in the file has a key that serves as a unique identifier for the string. CONTENTdm uses this key to look up the text string to display. Do not translate the key name (tuid).>/p>

For each key there is an English language string with language = "en". For each additional language the English string will be translated into another language and added to the key. The previous example shows the "About" string translated into Pirate English and Spanish.

Note: The following are important points for adding or editing the text strings in the languages file:

  • Some of the error messages contain a new line character \n. Please use \n to indicate a line break. Do not translate or capitalize \n.
  • Remember that single or double quotation marks are supported in only a few strings. Avoid using them if you can.
  • HTML encoding is supported.

After you edit the cdm_language.xml file, you upload your file using the Website Configuration Tool, and remember to check the related localization configurations.

 

To download the languages file for editing

You can download your current website languages file by using Website Configuration Tool > Tools > Language option. After editing the file, you use the same option to upload, preview, and publish your customized file.

To localize or customize strings per language or to add languages

There are two ways to edit the CONTENTdm strings:

  1. Microsoft Excel can be used to add a new language.
  2. XML or TMX Editor (OCLC recommends Olifant) is best for editing existing strings.

Important: Remember that the cdm_language.xml file must be UTF-8 encoded.

 

To add a new language using Microsoft Excel

The cdm_strings.xlsx file is a list of the unique keys (ID) and English strings (text_EN). You simply need to add a column with your language translation of the English strings and then merge the changes back into the cdm_language.xml file using Olifant (or another TMX editor).

 

  1. Download cdm_strings.xlsx from the User Support Center.
  2. Start Excel.
  3. Open cdm_strings.xlsx.
  4. To add new language, copy the English strings (column B) to a new column (column C). Then translate the text in the new column.
  5. Save cdm_strings_language.xlsx, e.g. cdm_strings_Italian.
    • Save As Unicode tab-delimited cdm_strings_language.txt file.
    • Use Notepad to open the cdm_strings_language.txt file and click Save As to save as UTF-8 encoded.
  6. Follow Olifant merge instructions (see below) to merge the changes back into cdm_language.xml file.
  7. Upload your customized cdm_language.xml file on the Website Configuration Tool > Tools > Language page.

 

To merge changes using Olifant

For information about the merge logic in Olifant, click Help > Dialog Boxes > Merge Options.

  1. Create a tab-delimited text file using Excel or other editor.
  2. Copy cdm_language.xml to cdm_language.tmx so Olifant will recognize the TMX format.
  3. Start Olifant.
  4. Open the cdm_language.tmx file.
  5. Check that the file encoding is UTF-8 (from the Edit menu, select Attributes, and then click General.)
  6. In the main window, choose the source and target languages.
  7. Import the tab-delimited text file you want to merge:
    From the File menu click Import > Tab-d file.
    • Select tab-d file that has ID column and text column(s). Each text_NN column is a different language, e.g. text_EN, text_ES, text_DE.
    • Columns to import: Only ID and target language Text columns should be checked. Uncheck all others. If you didn’t modify text_EN then you don’t need to import it. You must import ID as the field on which to match.
    • Set attributes for ID column: Field type = Identifier (ID)
    • Set attributes for Text column: Field type = Text, Language = nn (e.g., "de" for German).
    • Note: Language must already exist in the cdm_language.xml file. If you are adding a new language, go to Edit > Languages; click Add; type the language code.
    • CONTENTdm uses Zend Framework language code format. Specifically, language codes are of the form [language]_[REGION], for example, "de_AT" or "zh_TW". For more information on Zend_Translate or details on language code handling, please consult the Zend documentation at http://framework.zend.com/manual/1.11/en/zend.translate.additional.html#zend.translate.additional.languages.
    • Check the boxes for First line is the header, Flag Imported Entries and Merge Entries.
  8. Click Merge Options button.
  9. Choose ID as the “Field in current TM” and “Field in the file to import”
  10. Check only the text column you want to overwrite (e.g., text_DE for German).
  11. Click OK to process the file merge.
  12. Review results in Olifant. The flagged records are new keys in the cdm_language.xml file. Delete any new records that were added in error. The only time you should keep flagged imported records is if you are adding new strings for customizations you made.
  13. Export your TMX file in the "Heartsome" format. This format defaults to lowercase language keys.
  14. Exit Olifant
  15. Rename your file with a file extension of "xml" (e.g. cam_language.xml)
  16. Open the .xml file in an XML or text editor. Search and replace composite language codes to the correct format. For example, change "zh-tw" to "zh_TW". Save the resulting file, ensuring that the UTF-8 encoding is preserved.
  17. Upload your customized cdm_language.xml file.

 

To edit using Olifant

  1. Copy cdm_language.xml to cdm_language.tmx so that Olifant will recognize the file.
  2. Start Olifant.
  3. Open the cdm_language.tmx file.
  4. Check that the file encoding is UTF-8 (from the Edit menu, select Attributes, and then click General.)
  5. If you are adding a new language, from the Edit menu, click Languages, and then click Add.
  6. Enter the language code (see above for format).
  7. Optionally review field settings. From the View menu, click Field Settings. Rearrange the order of the language columns as desired or hide languages that aren’t needed.
  8. Note: You should show the ID as Read-Only. The ID is the key that CONTENTdm uses to lookup the text to display on the website. Do not edit this.  

  9. In the main window, set the Source and Target Languages. The source language is English "en" and the target language is your translation language.
  10. Translate or edit the text of each entry.
    Tip: Use the Find icon to search for specific text. This is particularly useful if you are viewing the CONTENTdm website while localizing.

  11. If you are customizing your website and want to add custom text strings to cdm_language.xml, you can do so by adding a record with your own ID. The ID should be CUSTOM_KEY_abc, where “abc” is the text string identifier. Edit > Add will let you add a record. View > Generic Edit Field will open a frame that enables to you edit the columns.
  12. Export your TMX file in the "Heartsome" format. This format defaults to lowercase language keys.
  13. Exit Olifant
  14. Rename your file with a file extension of "xml" (e.g. cam_language.xml)
  15. Open the .xml file in an XML or text editor. Search and replace composite langugae codes to the correct format. For example, change "zh-tw" to "zh_TW". Save the resulting file, ensuring that the UTF-8 encoding is preserved.
  16. Upload your customized cdm_language.xml file.

 

To upload your customized cdm_language.xml file

After editing the cdm_language.xml file, you can use the Website Configuration Tool > Tools > Language option to upload, save, and publish your customized cdm_language.xml file for the entire website (global level) or for collections. You must refresh the Website Configuration Tool after you upload your language file in order to see the languages that are available. Remember to proof the changes on the website to make sure the translations or customizations are appropriate.