Views
Language Packs
From alfrescowiki
Contents |
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 Language Packs Forum 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
- The Alfresco Share collaboration application
- Content model labels (types, aspects, property names, etc.): http://wiki.alfresco.com/wiki/Data_Dictionary_Guide#Model_Localization
- 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.
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 here.
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.
Tips
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
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.
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
<!--
<config evaluator="string-compare" condition="Languages" replace="true">
<languages>
<language locale="fr_FR">French</language>
<language locale="de_DE">German</language>
<language locale="ja_JP">Japanese</language>
</languages>
</config>
-->
- If you wish override to set default language you need to add the attribute replace="true" to the <config> element
