Hyland Connect

resplin · ‎06-29-2015

Language Packs

This page is about how to translate the standard web interfaces shipped with Alfresco. Other interfaces will have their own translation process.

Storing translated content within Alfresco is addressed on the page Multilingual Document Support.

How to Obtain Language Packs

The main sources of language packs are:

Officially supported language packs: The documentation contains a list of official product translations, with new languages being added regularly.
Community language packs: Community provided language packs exist for many languages. You can find mature language packs in the Alfresco Add-ons directory, and language packs that are in the process of being collaboratively translated are usually at CrowdIn.
Partner language packs: Alfresco partners in some geographies provide commercially supported language packs for their customers.
Custom language packs: Sometimes it is useful to create your own language pack that follows organizational terminology guidelines.

Installation

Officially supported language packs are included in the product and require no installation. The correct language pack for the Share interface is selected through the browser language preferences, and the Explorer interface language is selected through a dropdown menu at login.

The best way to install other language packs depend upon how they are packaged. The language pack author should provide installation instructions. More details on packaging options are below.

The translations at CrowdIn are not packaged for installation yet. In order to use those translations, you will need to install them yourself, probably using one of the packaging methods below.

Getting Help

If you have any questions or problems, you should reach out on the Alfresco Discussions tagged as #i18n or the Alfresco Translators Mailing List.

Language Pack Development

Overview

No special programming knowledge is required to start developing a language pack. Alfresco uses standard Java message bundles to provide localized messages within the application. This allows language pack authors to develop translations without needing to modify any core Alfresco files.

Language packs for Alfresco consist of:

text files containing the localized messages in the appropriate directly structure,
optionally, a README with the license information and installation instructions,
optionally, a glossary file containing standard terms and translations that should be consistently used in the project.

You can get details on how to manage a community translation project on the page Community Translations.

What Can Be Translated?

Almost all parts of the Alfresco application can be localized by language pack authors, including the following main components.

The Alfresco Explorer web client (removed in Alfresco 5.0)
The Alfresco Share collaboration application, including the new Aikau framework
Content model labels (types, aspects, property names, etc.): http://docs.alfresco.com/5.0/concepts/content-model-localization-share.html
System-level messages (e.g. for logging)
TinyMCE plugin: there are many TinyMCE language packs already available

The project is organized into root folders like this:

alfresco/ : contains all repository strings (content models, workflows, templates, error messages) and the Alfresco Explorer interface strings (webclient.properties file). These files can be easily installed by placing them in a alfresco/messages folder on your classpath.
share/ : contains all Share web interface strings. The internationalization framework used by Share requires message files to be broken down into various sub-folders. Most of the strings are in slingshot.properties, which is the first file you should translate. Next you should probably translate web-client.properties and common.properties.

Project Structure

The following directory structure is suggested when developing your language pack, as this will allow you to easily package up your project for testing and distribution. This layout is also designed to be consistent with that used for AMP Files making it easy to package your language pack up in this manner if you wish.

/
|
|- config/
  |
  |- alfresco/
    |
    |- messages/
      |
      |- action-config.properties
      |
      |- action-service.properties
      |
      | ...
      |
      |- workflow-interpreter-help.properties
    |
    |- site-webscripts/
      |
      |- org/
        |
        |- alfresco/
          |
          |- components/
            |
            |- calendar/
            |
            |- ...
            |
            |- title/
          |
          |- modules/
|
|- glossary.txt
|
|- readme.txt
|
|- project-build.xml (optional)

The packaging process needs to add a locale suffix _fr_CA so that Alfresco can find the correct translation.

The project directory structure can be broken down as follows:

config/alfresco contains all message bundle files for containing your localized strings within two subdirectories,
- messages containing all global messages for the repository, web client and Slingshot
- and site-webscripts containing messages for all translated Slingshot modules and components
glossary.txt should contain a standardized list of all common terms used in your translation to ensure consistency is maintained. At a minimum you should look to document all terms from the Glossary of Terms in this file.
readme.txt should contain basic information about the language pack such as the details of all maintainers and any relevant project information such as acknowledgements or how to contribute.
project-build.xml can optionally be included to automate building and installation of your language pack using Ant.

Packaging Language Packs

Since Alfresco 3.3 language packs can be packaged for deployment into the Explorer or Share web applications in either AMP or JAR file formats. Both of these file formats are based on the widespread ZIP file format and can be packaged easily using standard tools such as Ant (see below). The various approaches to packaging are documented on the page Packaging_And_Deploying_Extensions.

Packaging in AMP format

AMP files contain a top-level config folder where classpath resources including configuration and (importantly here) message bundles should be placed. Therefore translated message bundles should be placed in the following directories within the AMP file:

config/alfresco/messages for standard Java message bundles
config/alfresco/site-webscripts for web script message bundles

AMP files conforming to the standard structure may be installed into an Alfresco installation using the Module Management Tool (MMT).

Packaging in JAR format

In contrast to AMP files, the contents of JAR files are not extracted into the web application upon installation. Instead, resources are loaded directly from within the JAR file. Therefore a simpler directory structure is used:

alfresco/messages for standard Java message bundles
alfresco/site-webscripts for web script message bundles

Once built, JAR files can be deployed into an existing Alfresco installation by placing them in the WEB-INF/lib folder inside the web application, or in an external shared location outside of the web appliation such as shared/lib in Tomcat.

Best practice is to build a JAR file containing your language pack, and then wrap it in an AMP so that it can be installed and maintained with standard Alfresco module management tools.

A script that downloads translations from CrowdIn and produces a JAR for each language (including the TinyMCE localization) is attached to this article.

Building Using Ant

The following build script may be used as the basis for building a translation distribution using Ant, assuming your project uses the directory structure above.

<project name='Alfresco Example Language Pack' default='dist-zip' basedir='.'>
   
   <property file='build.properties' />
   <property file='${user.home}/build.properties'/>
   
   <property name='locale.language' value='${user.language}' />
   <property name='locale.country' value='${user.country}' />
   
   <property name='locale.name' value='${locale.language}_${locale.country}' />
   
   <property name='locale.suffix' value='_${locale.name}' />
   <property name='config.dir' value='config' />
   <property name='scripts.dir' value='${config.dir}/alfresco/site-webscripts' />
   <property name='build.dir' value='build' />
   <property name='ascii.dir' value='${build.dir}/ascii' />
   <property name='classes.dir' value='${build.dir}/classes' />
   <property name='dist.dir' value='${build.dir}/dist' />
   <property name='dist.file' value='${dist.dir}/alfresco-langpack-${locale.name}.zip' />
   <property name='copy.verbose' value='false' />
   
   <target name='clean' description='Prepare for build'>
       <delete dir='${build.dir}' />
   </target>
   
   <target name='prepare' description='Prepare for build'>
       <mkdir dir='${build.dir}' />
       <mkdir dir='${ascii.dir}' />
       <mkdir dir='${classes.dir}' />
       <mkdir dir='${dist.dir}' />
   </target>
   
   <target name='build' description='Build property files ready for deployment' depends='clean,prepare'>
       
       <mkdir dir='${classes.dir}/alfresco/messages' />
       <mkdir dir='${classes.dir}/alfresco/workflow' />
       <mkdir dir='${classes.dir}/alfresco/web-extension/site-webscripts' />
       
       <copy todir='${ascii.dir}' verbose='${copy.verbose}' includeEmptyDirs='false'>
           <fileset dir='${config.dir}' excludes='**/*.properties' />
       </copy>
       
       <copy todir='${ascii.dir}' verbose='${copy.verbose}' includeEmptyDirs='false'>
           <fileset dir='.' includes='readme.txt' />
       </copy>

       <native2ascii encoding='UTF-8' src='${config.dir}/alfresco/messages'
           dest='${ascii.dir}/alfresco/messages'
           includes='**/*.properties' ext='.properties'/>
       
       <native2ascii encoding='UTF-8' src='${config.dir}/alfresco/workflow'
           dest='${ascii.dir}/alfresco/workflow'
           includes='**/*.properties' ext='.properties'/>
       
       <native2ascii encoding='UTF-8' src='${config.dir}/alfresco/site-webscripts'
           dest='${ascii.dir}/alfresco/web-extension/site-webscripts'
           includes='**/*.properties' ext='.properties'/>
       
       <copy todir='${classes.dir}' verbose='${copy.verbose}' overwrite='true'>
           <fileset dir='${ascii.dir}' includes='**/*.properties' />
           <mapper type='glob' from='*.properties' to='*${locale.suffix}.properties'/>
       </copy>
       <copy todir='${classes.dir}' verbose='${copy.verbose}' overwrite='true'>
           <fileset dir='${ascii.dir}' includes='**/*.txt' />
           <mapper type='glob' from='*.txt' to='*${locale.suffix}.txt'/>
       </copy>
       
   </target>
   
   <target name='dist-zip' description='Create ZIP file of the language pack' depends='clean,build'>
       <zip destfile='${dist.file}' basedir='${classes.dir}' />
   </target>
   
</project>

By default the script will use your session locale to set the locale suffix for the language pack. If you want to specify a different locale you can do so using a command-line argument, e.g.

ant -f project-build.xml -Dlocale.name=cy_GB

Translation Tools

At the most basic level, all that is required to develop a language pack is a simple text editor. However since language packs usually consist of a number of files some of which can contain several hundred messages, you may wish to consider using a more specialized translation tool such as the ones listed below. Some of these tools also provide other benefits such as translation memories which will assist you during the translation process and automatic highlighting of untranslated messages.

Most community organized translation projects are using the CrowdIn collaborative translation service. See Community Translations for details.

The following is a list of applications which have been used by other translators to help with their localization efforts. Note that these will vary greatly in the way in which they work and the capabilities they provide, but if you choose a tool which supports standards such as XLIFF or TMX this will allow others to use a different tool of their choice.

Attesoro is a Java-based application which provides simple file-based editing of your translations, automatic encoding of characters, and highlighting of untranslated entries. You can download it from http://attesoro.org/, then simply start it and open one of the *_en_US.properties files to start translating. Note that Attesoro is known to have issues encoding some quotation marks correctly and you will need to manually fix these afterwards.

OmegaT provides more advanced capabilities such as fuzzy matching, translation memory, keyword search, glossaries, and translation leveraging into updated projects based on the TMX format. See http://www.omegat.org/en/omegat.html.

The Open Language Tools are a set of translation tools, using standards such as XLIFF & TMX to manage localized messages. Available from http://open-language-tools.dev.java.net.

Properties Editor can directly edit property files written in Unicode reference characters, and saves the time and effort of converting into Unicode through native2ascii. In addition to the usual functions of an editor, the plugin is integrated with Eclipse and JBuilder. Files can be opened in the IDE and saved in Unicode.
For details, see
http://propedit.sourceforge.jp/index_en.html.

The native2ascii tool bundled with Sun's JDK can be used to ensure that non-ASCII characters in your message bundle files are correctly encoded and can be useful if your editor does not fully support automatic encoding.

Virtaal provides rich translation memory from various sources, searching, glossaries, etc. It supports XLIFF and PO editing. http://virtaal.org

Translate Toolkit provides a prop2po tool that is able to convert Java properties files into Gettext PO files. This allows a translator to make use of any FOSS translation tool such as Virtaal. Java files are automatically unescaped for PO so that you can edit using proper Unicode characters. po2prop will escape the Unicode characters as needed.

Alfresco Localisation Tools is a script prepared by David Webster to assist with common localization tasks such as encodings, finding untranslated strings, detect duplicate definitions, etc.

Tips

General Tips

Most translation efforts should start with Share's slingshot.properties file, as that will have the most common strings in the Share User Interface.
CrowdIn has two levels of permissions: translate and validate. The leaders for a language can decide to restrict who has validate permission.
Some phrases have placeholders such as '%s'. When running, the software will insert a value in that place. They should not be removed, but they can be moved to wherever they will make the most sense in the translation.
If the message contains a variable e.g. {0} then single quotes must be doubled up to escape them correctly e.g. convert: don't to: dont. If the message does not contain a variable then a single quote character should be used.

Date and Time Localization

Be cautious when translating date format strings like 'mmmm yyyy'.

There are two types of date format strings in properties files:

Those displayed to the user to indicate the format for input of a date.
Those used programmatically by the system to format dates.

User Input Formats

These are scattered a bit, but the property key is usually suffixed by '.display'. They should be translated to help the user understand the date format.

Programmatic Date Format

These are almost universally centralized in the common.properties file.

You can change these to represent the accepted date format for the local, but they need to be valid format strings. In other words, though the order can change they need to use the same date component identifiers regardless of the language. e.g. if an English date 18-02-2014 (DD-MM-YYYY) wants to be formatted different in the German locale: 18/02/2014 then the valid identifiers ('DD', 'MM' and 'YYYY') still need to be used; even though German for 'year' is 'jahr', you'll get an error if you replace 'YYYY' with 'JJJJ'.

There are various different, and incompatible, syntaxes for specifying date formatting strings. Since 4.0, we standardized on client processed dates and we use the syntax supported by Alfresco.util.formatDate which can be found here:
http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html

And a good tutorial is here:
http://blog.stevenlevithan.com/archives/date-time-format

Exceptions to this rule should be noted in any comments in the properties file, e.g. date-format.rfc822 in common.properties which needs to be in a freemarker compatible format!

Projects that use CrowdIn can mark these strings as not being translatable in order to prevent accidents that introduce problems.

Updates

As changes are made in future releases of Alfresco you will need to ensure that you maintain your language pack by keeping up with these. Most translation tools will use a translation memory to translate duplicate strings between versions, but you can also use a diff against the source code repository to identify what has changed.

Multi-byte Encoding

The properties files for Alfresco Workdesk are UTF-8 encoded.

All other properties files in the product are Java standard x-US-ASCII-ue, which is Unicode escaped US-ASCII. To edit the files, they need to be converted to your local character set using the native2ascii utility that is shipped with Oracle Java.

Decoding the file on a Linux system would require this command:

native2ascii -reverse -encoding utf8 {filename}

Before checking your modifications into source control, you will need to re-encode it using the same command without the '-reverse' flag.

To view language packs for languages such as Japanese and Russian, you will need to have an appropriate multi-byte font installed on your computer. For example, 'Arial Unicode MS' on Windows PCs.

Records Management

It is important that a translation of the Records Management module uses legally acceptable language for the destination locale. In order to assist with this process, start by researching the most appropriate translations for the key English terms in this list: Alfresco_RM_Term_List_EN_20140113.xls. Then stick with those standard translations.

Adding a Login Language to Alfresco Explorer

To change the language options offered on the login screen, you need to modify the web-client-config-custom file (you may need to rename the sample file):

Edit 'web-client-config-custom.xml' file in the <custom config>/extension folder
Find the '<languages>' section
Add or remove language entries of the form '<language locale='XX_YY'>LangName</language>'
Save the file

If you wish override to set default language you need to add the attribute replace='true' to the <config> element

Hyland Connect

Language Packs

Table of Contents

Language Packs

How to Obtain Language Packs

Installation

Getting Help

Language Pack Development

Overview

What Can Be Translated?

Project Structure

Packaging Language Packs

Packaging in AMP format

Packaging in JAR format

Building Using Ant

Translation Tools

Tips

General Tips

Date and Time Localization

User Input Formats

Programmatic Date Format

Updates

Multi-byte Encoding

Records Management

Adding a Login Language to Alfresco Explorer