Views
Language Pack Development
From alfrescowiki
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 simply consist of a number of text files containing the localized messages plus a short README and glossary file.
Alfresco includes in the official product translations for English, French, Italian, German, Spanish, and Japanese. Community provided language packs exist for many other languages. You can find community language packs at Alfresco Add-ons.
No special programming knowledge is required to start developing a language pack. Community developed language packs should host with a popular code hosting service such as GitHub, BitBucket, or Google Code in order to use their source control systems to keep track of all changes which are made to the translation. It is also recommended that you list your language pack in Alfresco Add-ons directory so that others can find your language pack.
Contents |
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
- The Alfresco Share collaboration application
- Content model labels (types, aspects, property names, etc.)
- System-level messages (e.g. for logging)
All components other than Share are composed of a number of message files which can be easily installed by placing them in the alfresco.messages package on your classpath. For Tomcat installations, the normal directory used would be tomcat/shared/classes/alfresco/messages within your Alfresco installation.
Share components are based on a different internationalization framework which requires message files to be broken down into various sub-folders. This has implications for how your language pack structure should be set up.
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)
Files within the language pack should not have any locale suffix, (e.g. _fr_CA) as this will normally be added automatically by the build process.
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 Alfresco 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).
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.
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.
The following is a list of free and open source 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.
CrowdIn is a web service to assist with community translations. It is free for use by open source projects. A team of Russian users setup an Alfresco project and can add other languages and contributors. To be added, contact user resplin or aviriel either on #Alfresco or in the Forums.
Keeping up to Date
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. You may wish to consult the Message Bundle Diffs when a new version is released, this will highlight the message strings that have been added, removed or modified in the new release.
