Translating Tutorial | User guide | Zenphoto - The simpler media website CMS

User guide

Translating Tutorial May 16, 2008

Categories:

Note: This tutorial refers mainly to the nightly build/svn version of Zenphoto since localization/translation is a work in progress. Zenphoto includes a file "zp-core/functions-l18n.php" that contains a prefdefined list of languages and their related locales. Check this list to be sure your language is included. If it is not there, let us know and we will add it.

What should I know before starting a translation
How does Zenphoto's translation work?
Language files and naming conventions
Starting a new translation
Updating/modifying an existing translation
Plugin and theme translations
- Plugin translation
- Theme translation
Joining separatat translation files
Updating the Zenphoto release via SVN

What should I know before starting a translation?

Before you start check out the translations page to see which languages are available or look at the translation tickets on the trac to see on which worked is in progress or help is needed. Also check the nightly builds to see if perhaps work is completed and a language files released.

It would be good if you were quite secure in written English and quite comfortable with Zenphoto itself and with web developement terms in general, even if you no coding is required when making a translation.

If you don't find any ticket for your language (ask on the forum if unsure), open one for it. If you want to do the translation yourself, assign the ticket to yourself and accept it.

Keep in mind that if you volunteer to make translations there will be the need of updating the languages files at least for every official release since Zenphoto is a work in progress. You may make your translation based on the current release of zenphoto. Then it can be provided to most Zenphoto users.

Nightly build or official release?

However it is recommended to make your translation against the nightly builds. This way it will be ready for and matched up to the next release of Zenphoto. Currently there are over 3600 strings that need to be translated. Some are only single words though, some are doubled for specific reasons. Since we change strings here and there all the time we recommend doing updates frequently at least once a week, so it will be much easier to match a given release date of the next version. You simply will have less that way than doing all at once. So better think twice before your volunteer...:-) More on that in detail later.

Mailing list

You should join the Google Zenphoto translator's group. There you will find other like-minded people and be able to ask questions and share experiences. Also the developers post pre-announcements of up-coming Zenphoto releases to this group to give you a heads up so you can get your translations into that release. This is also the place to ask for the credentials to update the release package with your translation files yourself. For more on this please read about how to update Zenphoto using svn.

Licence of your translation

Just to note: Since a translation falls under copyright, your translation should be provided under a open licence compatible to Zenphoto's GPL v2 licence. If no special licence note is attached, we will assume GPL.

How does Zenphoto's translation work?

Zenphoto uses the gettext technology to provide translation and localization capability. Currently this requires native gettext support, meaning gettext needs to be installed as a PHP extension on your server. But there are plans to provide a replacement for servers without native support some time in the future.

Zenphoto uses the message-level for translation. We use the standard gettext function gettext() to translate strings. If you are working with Zenphoto you might have spotted strings that look like this in the code:

Singular:

<?php echo gettext("some text"); ?>

Plural (actually rarely used):

<?php echo ngettext ("Delete the selected file?",  "Delete the selected files?",$var); ?>

If a translation is found, "some text" will be replaced by the translation string. If no translation is found, simply "some text" is used.

Additionally Zenphoto uses translatable format strings rather than gettext fragments only (post Zenphoto 1.2). You will also see strings that look like:

Singular:

<?php echo sprintf(gettext('Album %1$u of %2$u'),$var1,$var2); ?>
<?php printf(gettext('Album %1$u of %2$u'),$var1,$var2); ?>

Plural (actually rarely used):

<?php echo sprintf(ngettext('%u  comment', '%u  comments', $var), $var);  ?>
<?php printf(ngettext('%u  comment', '%u  comments', $var), $var); ?>

The things which begin with % are parameters that get filled in at runtime. We are using sprintf/printf to format the output. If you are not familiar with these functions you can review the format variables here: http://us3.php.net/manual/en/function.sprintf.php.

The quick lesson is that the above example has two numbers that will be filled in at runtime. %1$u is the first in the list and %2$u is the second. So the output from this would look like:

Album 5 of 10

If you wish to reverse the order of the elements you just change their place in the string while translating:

'Of %2$u albums this is number %1$u'

would yield

Of 10 albums this is number 5

In short: These variables are required to be included in your translation as well as any html code that may be within a string.

Which language translation to use you can set within the admin options of Zenphoto. There is a separate option for setting the date-format, too. The translation is provided then for the admin interface, setup.php and the standard themes and plugins included in the distribution. Month and day names do not need to be translated manually, these will be done automatically by your server, assuming that your server operates on your (chosen) country's locale.

Language files and naming conventions

Zenphoto gets the translation terms itself from a .mo-file (machine object file). This file is binary and contains either the original text and the translation. But the actual file to translate is a .po-file (portable object file).

Both files are stored within zp-core/locale with the following standard folder structure:

de_DE/
de_DE/LC_MESSAGES
de_DE/LC_MESSAGES/zenphoto.po
de_DE/LC_MESSAGES/zenphoto.mo

The folder structure and the filenames are mandatory. You would have to provide an archive of exactly this structure for your language.

Since the .mo-file is binary, you can't work directly with it, so you have to work with the .po-file instead. This is a normal text file, that looks like this:

msgid ""
msgstr ""
"Project-Id-Version: zenphoto 1.1.5 svn\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2008-04-09 17:50+0100\n"
"PO-Revision-Date: 2008-04-09 17:56+0100\n"
"Last-Translator: john smith <john@smith.net>\n"
"Language-Team: john smith\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Poedit-Language: German\n"
"X-Poedit-Country: GERMANY\n"
"X-Poedit-SourceCharset: utf-8\n"
"X-Poedit-Basepath: /Applications/MAMP/htdocs/zenphoto-svn/\n"
"X-Poedit-SearchPath-0: zp-core\n"
"X-Poedit-SearchPath-1: themes\n"
#: zp-core/admin-functions.php:169>
msgid "A reset request has been sent."
msgstr "Eine Reset-Anfrage wurde gesendet."
(...)

You can edit this file with any text editor. But you have to transform it into a .mo-file to be used for translation. There are several tools that can do that for you:
The official GNU gettext package includes command-line tools, but you might prefer a real editor with a GUI. For Linux based systems there are for example LaunchPad or KBabel and others, but considered the standard tool for this is Poedit which is available for Windows, Mac and Linux. We would recommend Poedit (well, we don't really know the others..:-)) and the description in the next section uses it. But probably the setup for another editor will be not that different.

Upload page upload button: Zenphoto 1.2.5 introduced a new multi file flash upoad that does not allow special characters due to a limitation of the flash script. This requires the creation of an image with your translation serving as the upload button. This button must be named select_files_button.png placed in above folder structure:

de_DE/select_files_button.png

We have preprepared a .psd template file for download with instructions in the attached read me file.

Language flag image: Zenphoto 1.3.2 will introduce a "visual" language selection feature. For this an 24 x 16 px image named flag.png must be placed within your locale folder:

de_DE/flag.png

Should the image be missing an "error flag" will be substituted.

Submitting the translation

If you finished your translation (at least 90%) and think it is ready for release, please zip the entire folder setup described above and rename it like this:
<locale>-<zenphoto version>.zip (example: de_DE-1.1.7.zip for the zenphoto 1.1.7 release)

Then attach it to your translaton ticket and set the ticket version to the coming Zenphoto version. We will than see that this file is ready for the release and will add your translation file to the svn so it is included in the release package. If you are a frequent contributor and wish to translate regulary you could also ask us for svn credentials to submit your files directly via svn on the google translate mailing list.

If you just want others to test or help with a svn/nightly translation, please rename the attached zip-file like

<locale>-nightly<date of nightly> (example: de_DE-nightly2008-06-30)
<locale>-svn<svnnumber> (example: de_DE-svn1822).

In the above examples the German locale "de_DE" is used. Here are two lists with some locales for example:

Starting a new translation

There are basically two ways to start on a translation: You could use one of the translation files included in the Zenphoto distribution and change it to your language. Or you can parse the Zenphoto package yourself using Poedit.
The second is the way we would recommend, because you then can be sure that you don't miss any string since we update and change all the time. And it saves workload if you update the file more often than just once when a new version comes out.

Download and install Poedit.
Download the latest nightly build of zenphoto and extract the files the same folder where Poedit is or a folder level below. Poedit needs a absolute path to work correctly. This does not need to be within a localhost server setup like WAMP, LAMP or MAMP, but of course this would be very useful to test your translation.
On Mac OS X the folder to parse is best located on the same level or below Poedit's location in the Applications folder, since the paths to are relative from Poedit's location:
Zenphoto folder: <harddrive>/Applications/MAMP/htdocs/zenphotoPoedit: <harddrive>/Applications/PoeditAlso working is simply the folder (as used on 6.):
Zenphoto install: <harddrive>/Applications/zenphotoPoedit: <harddrive>/Applications/PoeditOn Windows that folder setup seems not to be that important.
Do not install any additional plugins or themes besides the already included ones as some may included additional gettext calls (and separate translation files) that are not necessary for Zenphoto's own translation file and bloat the file unnessecarily.
Then open zenphoto/zp-core/locale in your zenphoto installation, duplicate the de_DE folder or any other folder and rename it to match your locale.
Now open Poedit and select "New Catalog":
In the appearing setttings window enter your data. Most are pretty obvious, only language, country and charset are mandatory. Set the charset to UTF-8. Then you have to enter the string for "Plural forms" because in a few places Zenphoto uses gettext plural forms. For example English has two forms (e.g. day/days) so this would be nplural=2; plural(n !=1);. Other languages require different settings. More info about that on the gettext plural page.
Next you need to set the path of the zenphoto folder to parse. (See also 2.) Remember that it is important to divide a path like this C:\Programs\zenphoto into the base path C:\Programs\ and the relative path zenphoto (Mac OS X example shown below). You can ignore the keywords tab, because Zenphoto uses the default gettext keyword
.
In the appearing save window change the name of the file from default.po to zenphoto.po and save/overwrite it within your new zenphoto/zp-core/locale/<your locale>/LC_MESSAGES/ folder (in the image the German locale is used as example).
You will now see that Poedit searches the zenphoto folder for gettext calls.
When finished, simply hit "Ok". Don't get confused if Poedit notes a "Poedit Error". It's actually a display bug (at least in the Mac version), there is a "done" on the right. Everything is fine, no strings harmed.
Now you see on the left the original english strings. Klick on an line and you can enter the translation for it below. The two field on the right bottom can be used for comments to the translation, but are not really important now. Singular translation will look like this:
Plural translation will look like this (see also here about plural strings):
Sometimes you will encounter HTML markup within the strings to translate. We have included them because some languages have a very different syntax that might require changing the order within a string. These markup needs to be included within your translation, too. Also you might think that some strings are completly useless like a lonely ")" or the double point in "View image:" for example. It's not forgotton, but on purpose. There are languages that use not only differenty syntax but completly different characters, too. And some even write from right to left, so these characters need to be changeable, too. Sometimes you might see a string that you don't need or want to translate. Something like "SpamAssassin" is most likely a fixed term for example. You can leave that field empty, but it's recommend to fill in the same term, so simply use the context menu to copy the original string to the translation field.
Some sentences are hard to translate without knowing the context. Poedit's context menu will show you were in Zenphoto the referring string is used.
When you are done with translation just hit save and Poedit automatically generates a .mo-file that is used for the translation called zenphoto.mo. Now you should check your translation with Zenphoto. It's recommended to use your zenphoto folder as a base for future translation updates, so that you don't have to change the parsing path for Poedit all the time. Don't forget to create a upload button!
To submitt your translation to the zenphoto team generate an archive of your locale folder with all its subfolders and upload it to the translation ticket. Since we probably will provide the files as a additional downloads, a common type like .zip or .tar would be good. We actually would prefer if you use SVN to update the release package directly. For more on this please read about how to update Zenphoto using svn.

Updating or modifying an existing translation

If you choose to update or modify your own translation or a translation someone else had provided, you can just open the .po-file of that locale with Poedit. IMPORTANT: If that file was not generated by you, you would have to check and change the path to parse to match your zenphoto folder in Poedit's settings!
If you have done that, hit "Update" and Poedit will now compare the translation file with the zenphoto folder to check if and what strings have changed.If Poedit finds untranslated strings, they will be listed in the window below you already know. The second tab then will show strings that are not used anymore. These will be deleted from the file. (None found in this example).
If you have worked in that language before, Poedit might have collected some terms in its internal dictionary and will try to autotranslate some strings. These strings are then marked in a dark yellow as "fuzzy". Most of the time Poedit is fairly wrong with its guesses though, so don't count on that.
Blue strings are apparently empty, while successfully translated are printed in black (freshly translated ones are marked with a little star). Poedit lists the percentage of translation, the total number of strings plus the fuzzy strings (autotransation attempts), the bad ones and the untranslated in the bottom left footer.
When you are finished with you update, hit "Save" again and the .mo-file gets automatically updated. Don't forget to create a upload button if necessary!

Plugin and theme translations

Important note: This section refers to a feature coming with Zenphoto 1.3.2 because the earlier version of this feature was buggy in prior versions. It can be previewed in the svn versions or the nightly builds.

If you provide a theme or plugin as a third party, its translation is naturally not included with Zenphoto’s general translation file. But with post Zenphoto 1.3.2 it is possible to have independent translations files for your theme or plugin.

Plugin translations

To set up your plugin for separate translation, you need to enclose every string in your plugin that should be translatable with this special function instead of the standard gettext():

<?php gettext_pl('<string to translate>','<plugin name>'); ?>

This function tells Zenphoto that this string uses its own plugin translation. You should not mix standard gettext() with this in your plugin as Poedit would read these as well and add them to the translation file unnecessarily.

If your plugin consists of just one single file <plugin name>.php, you have to create an additional folder of the same name next to the plugin file. Use exact this folder setup:

/plugins/<plugin name>/locale/<language locale>/LC_MESSAGES/
/plugins/<plugin name>/locale/<language locale>/LC_MESSAGES/<plugin name>.po
/plugins/<plugin name>/locale/<language locale>/LC_MESSAGES/<plugin name>.mo

Now setup Poedit as described above but only to parse your plugin's folder. Additionally you have to add the keyword "gettext_pl" to Catalog > Settings > Keywords so that the special plugin translation strings are recognized.

Theme translations

There are two sources of strings that need to be translated for a theme/site:

The first is items in your database such as image and album descriptions. For these to have multiple languages you will need to have to enable the multi-lingual feature. See the multilingual sites tutorial about this.

The second and most prominent is the literal strings in the PHP code that this tutorial refers to. Themes which are included with the Zenphoto distribution are also handled by the normal processing as described above.

To set up your theme for separate translation, you just need to enclose every string in your theme that should be translatable with this function instead of the standard gettext():

<?php gettext_th('<string to translate>'); ?>

This function tells Zenphoto that this string uses its own theme translation. You should not mix standard gettext() with this in your theme as Poedit would read these as well and add them to the translation file unnecessarily.

For the general theme description on the theme's tab you have also to add the theme's name as a parameter:

<?php gettext_th('<string to translate>','<theme name>'); ?>

You also need need to have a locale folder set up within your theme’s folder this way:

/themes/<theme name>/locale/
/themes/<theme name>/locale/<language locale>/LC_MESSAGES/
/themes/<theme name>/locale/<language locale>/LC_MESSAGES/<theme name>.po
/themes/<theme name>/locale/<language locale>/LC_MESSAGES/<theme name>.mo

Now setup Poedit as described above but only to parse your theme's folder. Additionally you have to add the keyword "gettext_th" to Catalog > Settings > Keywords so that the special theme translation strings are recognized.

Joining separate translation files

Poedit provides the translation memory feature that is a kind of dictionary/database to make this task easier. Some resources:

Updating the Zenphoto release via SVN

Zenphoto uses an SVN repository to manage its changes. Translators
are advised to request credentials to the make updates to this repository. Use
the contact form for this request.

Using the SVN both keeps you abreast of language string changes as
they happen and allows you to keep even the nightly builds current with your
language.

There are two “branches” in the repository. The “trunk” branch
represents the current (or soon to be current) release of Zenphoto. The “development”
branch represents the new development to Zenphoto. It is most important that
the “trunk” branch be up-to-date in its translations as formal releases are
made from it. But it is also convenient to keep the “development” branch
up-to-date to avoid the spectra of large amounts of strings to translate during
the last two weeks before a new release.

Basic instructions how to use SVN

This instructions are with screenshots from SvnX on Mac OS X as a client. But the usage principle will be the same anywhere.

After you installed the client you as said maybe have to install the svn binaries as well (those manage the svn respositories actually).
In your client you have to setup the svn repository to access. Note there are actually two repositories. That is the Zenphoto one where you have to set your id/password.
Now you have to checkout a working copy that to any place on your computer. Could be within your local server to have a valid svn managed install or elsewhere if you use it just for translation. (Export means it is exported plain without svn stuff - those are invisible folders like .svn): NOTE: If you use Poedit for translation the checkout needs to be within the applications folder (at least on Mac!).Poedit otherwise may fail to parse the files for gettext strings to translate.
Now define the svn install in the "working copies" window. This is an example of working copies:
If you click on a working copy you see in the new window some files printed bold. Those are the changed ones. You can now uses the "Commit" button (2nd row of buttons) to send these to the svn. To update a svn working copy just click the "Update" button (1st row). You need to do this frequently unless we proposed "string freeze" shortly before a release in case strings changed. Then you have again to parse the install using Poedit (or else) to get the new strings.