Translating ccHost

Also see ccHost Localization.

This document describes the procedures used to create and maintain translations for ccHost after the ccHost 2.9 Release.

Supported Languages

The latest release of ccHost includes support for multiple languagues, depending on who from the community submits languages for localizing the project.

Anyone wishing to assist should sign up on the ccHost mailing list.

Known Issues

• XML pages need translation.
  • Currently only strings php and inc files are correctly identified and set up for translation.
• Auto-detection
  • There needs to be auto-detection of languages at installation and first session installation.

Getting Started

Translations for ccHost are stored in gettext message catalogs. Message catalogs are text files which associate translated strings with identifiers used by the application. Each string to be translated is referred to as a "message". The cctools mailing list is used for managing translations for ccHost. If you are translating ccHost into a new language, you are encouraged to join this list. The addition of new messages to be translated will be announced there, and you may ask questions on the list regarding internationalization. The availability of new message catalogs will also be announced on that list.

Creating A Translation

When translating ccHost there is one file which must be copied and edited. The translation resources are located in the locale/default subdirectory inside of a ccHost installation. Use the following instructions to create a new translation for ccHost; these instructions are for translating ccHost to the fictional "ya" locale and assume a Linux development environment.

• Create a locale subdirectory for your new translation

 $ cd locale/default
 $ mkdir ya
 $ mkdir ya/LC_MESSAGES

• Copy the template files into the new directory

 $ cp cchost.pot ya/LC_MESSAGES/cchost.po

• Edit the new files with the translated content. Two areas need editing: 1.) the header information and 2.) the messages.
  • The header information should be updated with the translator's contact information, email address and the character set used. The character set should usually be utf-8.
  • Each message is defined by two lines; the translated content goes between the quotes on the msgstr line. The msgid line must not be changed.

 ...
 msgid "OK"
 msgstr ""
 ...

• You may encounter strings such as "The file %s can not be found."; the %s should be left intact, as ccHost will substitute the actual piece of information at run time.

Translating using poEdit

poEdit is an Open Source cross-platform gettext catalogs (.po files) editor. It is built with wxWidgets toolkit and can run on any platform supported by it. It aims to provide more convenient approach to editing catalogs than launching Notepad (or vi) and editing the file by hand. Official releases are available from the poEdit web site for Windows and Linux. An alpha for Mac OS X is available at http://www.poedit.org/files/poedit-1.3.4-alpha.dmg. The poEdit team reports it is an early alpha, but some translators have had success using it for ccPublisher (another Creative Commons project).

Just use poEdit's File -> New catalog from POT file... function will easily doing so. It even can compile .po into .mo file in the same time you pressing Save.

Translating under Windows

To translate under Windows, download and install a ccHost 2.9 or greater release. In the installation directory you will find a the directory locale' which contains the subdirectory default. Create a new subdirectory under locale/default with a name matching your new locale. For example, to translate ccHost into French, create a directory named fr_FR.

The ccPublisher locale folder (full size).

Copy the template files from locale/default into your new directory; rename them from .pot to .po.

The .po files for the new locale (full size).

Edit each .po file per the instructions above.

Editing the .po file (full size).

If you are translating ccHost to your default locale, simply run ccHost to test your translation.

Editting a shortcut to ccp.exe to specify a locale (full size).

ccPublisher running with the French locale specified; note the File menu reflects the change to Dossier (full size).

Submitting a Translation

Once you have completed or updated a translation and tested it, you can submit it to the ccHost developers using the ccTools patch trackers. Add the locale information for your new translation to the title and attach the .po and .html files you created (either individually or in a zip/tar file).

Updating Translations

Strings are sometimes added or removed from the application during development cycles. At those times it is necessary to update the translation (.po) files with the new strings and translations.

Using poEdit

If you are using poEdit, you can use the Update from POT file... option. Go to the Catalog menu and select Update from POT file.... Select the .pot file which cooresponds to the translation you have open (i.e. if you are updating ccpublisher.po, select ccpublisher.pot).

poEdit will display the new strings it will add, as well as the obsolete strings it will remove.

Using GNU gettext tools

Constructing an updated POT file is pretty simple on Unix-like systems (mac/linux/etc):

 $ make

This automatically takes care of updating strings on languages, merging changes, etc.