Difference between revisions of "Hugin translation guide"

Revision as of 15:27, 14 November 2012

Introduction

This page intends to provide guidance to translators of the Hugin project. Some terminology is very specific or used in a specific way in hugin, making it hard to find a close translation that fits the context of hugin in another language than English.

Getting Started on translations

1. Get your language file

Each language version of hugin uses a different *.po file (just like "fr.po" for French or "ja.po" for Japanese) containing all the translated strings. The country codes use the ISO 639-1 naming convention.

In general, you need the latest *.po file, usually the one for the language you want to modify. You can download it from the Mercurial repository: in this list of files navigate to your *.po file, click on the file name and then use the link "raw" in the navigation bar to save the file (right click or ctrl-click: Save Link as...) to your local hard disk.

If there is yet no translation file for your language you can use the file hugin.pot and rename that using the above naming convention or just ask the developers list for assistance.

2. Edit your *.po file

To edit the *.po or *.pot files, use poedit (it is a cross-platform PO files editor which runs on Mac OS X, Unix and Windows) or kbabel (it runs on any KDE platform). Note that you don't have to translate everything if you don't have time or knowledge to do it all. Also check below for things that shouldn't be translated (like software names) or for some explanations on specific words.

Note: When using a version of Poedit before 1.4.3, editing comments directly in the right pane doesn't work, the text isn't saved into the .po file. To edit comments, use the "edit comment" dialogue from the menu. With Poedit 1.4.3 and later, please note that to see the comment window you have to check "View / Show comment window", and to be able to modify the comment you must go to "File / Preferences..." and check "Comment window is editable" in the "Editor" tab.

Messages marked as fuzzy are actually not used in the GUI, their English counterparts are used instead. This seems to be an automagic suggestion which naturally often fails, so compare a fuzzy translation with the original phrase.

3. Verify your translation

In order to test your new translation and as well save some time for the developers who apply your file to trunk it's recommanded to check your newly translated po file for syntax errors. It's also a good idea to temporarily load your new translation file into the latest available hugin build.

4. Submit your *.po file, or even better, commit your changes through Mercurial
- You can submit your edited translation via hugin's tracker on launchpad (you'll need a launchpad account to log in). Add the tags "translation" and "hugin" and attach your file.
- An even better solution, but which the first time takes you a few more minutes to set everything up, is to use Hugin's revision control system. For more information see Become a Power Translator below.

How to check the translated file for syntax errors

The best way to check if your newly translated XX.po file hasn't any error, is to run the following command in a terminal (if you are under linux)

msgfmt -c --statistics XX.po

(you will need to install the gettext package to use the msgfmt command)

If you get as output the number of translated, unstranslated and fuzzy strings the file is ok. Else you get error messages indicating the line where the errors resides. Open the po file in a text editor, look for the line where the error lives and fix it. Finally run again the above command until you get no errors.

Note: if you use Poedit, it gives you warning when the po file you are trying to save contains errors. In the error message read the line where the error is listed then close poedit and open the file in a text editor and look for errors in the specific line.

Common mistakes

Remember that the first line in a po file need to be commented as shown here (note the # sign at the beggining of the line)

# French translations for hugin package.
# Copyright (C) 2004 Pablo dAngelo
# This file is distributed under the same license as the hugin package.
# Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, 2004-2009, 2010.

Watch carefully for retaining placeholders:

If you take the following string:

Open "%s" file

the %s must remain the same in the translated string because it is a formatting placeholder where the code will display a variable (e.g. a filename, a number etc...) at run time. For example %s is a string and %0.3f is a number with three post-comma digits.

Watch out for the new line (\n) indicator at the end of the string. For example in the string:

This is a test for a new line string\n

The \n symbol must remain at the end of the translated string

Watch out for quotation marks ". They must be quoted as \"

Use your new translation file

poedit updates your PO file and creates a MO file for your language. You can rename your MO file into hugin.mo and replace the hugin.mo file from your current installation (don't forget to make a backup of the original MO file, just in case).

On Windows the MO file is in your hugin directory, in share\locale\XX\LC_MESSAGES\hugin.mo, where XX is your language.
On Linux the MO file is under /usr/local/share/locale/XX/LC_MESSAGES/hugin.mo
On Mac OS X the MO file is inside the hugin bundle: just click on Hugin.app and from the context menu choose "Show package contents", from there it's under Contents/Resources/XX.lproj/locale/hugin.mo (XX is your language code).

If you want to you can also rebuild hugin (doesn't have to be a heavy job when you only changed the .po file, the process only updates that part).

Contribute your Translation

The preferred way is for translations to be contributed via the tracker. If you don't want to use the tracker you can also post it as attachment to the mailing list, but the mailing list has a short memory and your hard work may be forgotten.

To use the tracker, you need a Launchpad Account.

You can submit our translation via the web or via email.

Web

Log on with your Launchpad account.
Start reporting a new ticket.
Enter a title/summary (e.g. German Translation).
Launchpad will look for duplicates. This is good for bug reports, but for updated translations you can ignore it, scroll down to the bottom of the page and hit the "No, I need to report a new bug".
On the reporting form, enter a description in the "Further Information" field, then scroll to the bottom and hit the link "Extra options".
There you will find an Attachment field. Hit it and browse to the .po file. When the bug tracker asks you if this is a patch: click yes, even though technically it isn't one. In this case it will help make developers aware of a file that needs to be reviewed and added to the codebase.
Click the "Submit Bug Report" button.

eMail

Reporting a new ticket by email works too, but there are some critical conditions:

Your email account must be registered with Launchpad.
You must have an OpenPGP key associated with it and known to Launchpad.
You must craft your email carefully. A misplaced space or a typo can doom your report.
To be safe, use TEXT email, not HTML -- a good habit anyway. In most email client you recognize the TEXT mode by the lack of a formatting toolbar).

The message:

From: your Launchpad-registered email address
To: new@bugs.launchpad.net
Subject: title of the bug
Body: description + carefully crafted commands. Commands are usually at the end of the body. One per line. Each command line starts with a single space.
Enter the command " affects hugin" to assign the report to Hugin.
Enter the command " tag translation" to tag the report as being a translation.
Attach the file(s) to the email.
Send. It takes about five minutes to process and you get an email back with the result.

Become a Power Translator

After adding your po file to Hugin's tracker, the developers still need to integrate it, which is not easy as it means dealing with conflicting version (but how should a developer know which one of two conflicting sentences in a foreign language is the right one?). Thus using the same Mercurial approach to translation reduces considerably the burden on the rest of the team and is very much appreciated. Translation is a development too!

So instead of adding your po file to the tracker, you can integrate it yourself. You'll first need a Sourceforge user account (register here if you don't have one yet. Then tell the developers on the mailing list what your user account is, so that they can grant you access to Mercurial, the revision control system (you'll need this before following the next steps).

The first time

For Windows users

1. Get and install TortoiseHg.
2. In the explorer create a new folder, e.g. hugin-hg. Then do a right click on the created folder and select "Clone" in the "TortoiseHG" submenu. Select the repository http://hugin.hg.sourceforge.net:8000/hgroot/hugin/hugin as source path and select "Clone".
3. Now select "Repository Settings" in the "TortoiseHG" context menu of the folder. In the section "Synchronize" add a new setting with an alias/name e.g. "writeRepo" and the URL ssh://YOUR-SOURCEFORGE-USERNAME@hugin.hg.sourceforge.net/hgroot/hugin/hugin , close the settings dialog. (This needs to be done only once.)
4. You can commit your (partial) results anytime: right-click on the folder and select in the context menu "Hg Commit..." - enter a short text describing what you did (e.g.: "updated French translation"), check that only your modified .po file is selected and click OK. Note that you can select only the "translation" folder instead of "hugin-trunk" if you modified only files within "translation".
5. Open the folder context menu, open "TortoiseHG/Synchronize". Select your in step 2 created setting in the combobox and select "Push". (Or you can also push from the "Repository Explorer".)

For Linux/Unix/OSX

1. Get and install Mercurial. (
```
apt-get install mercurial
```
on Ubuntu/Debian,
```
yum install mercurial
```
on Fedora,
```
emerge mercurial
```
on Gentoo)
2. Get the full Hugin source code.

hg clone http://hugin.hg.sourceforge.net:8000/hgroot/hugin/hugin  hugin

3. Do your translation work inside the folder src/translations
4. You can commit your (partial) results anytime by running the commands

hg pull
hg commit TRANSLATEDFILE.po -m "updated LANGUAGE translation"
hg push ssh://YOUR-SOURCEFORGE-USERNAME@hugin.hg.sourceforge.net/hgroot/hugin/hugin

Important: committed changes are only on your local disk. You must push them to SourceForge to make them available to the project.

The following times

The next time you want to work on the translations, you'll have first to retrieve the latest version of the files (as someone else might have modified something in the meantime) before working on it and then commiting it again.

For Windows users: Simply right-click your "hugin" folder and select "Synchronize" in the "TortoiseHG" menu. In the dialog select "Update" in the combobox "After pull" (You can select in the settings under "Synchronize" that this is the default setting). Now select "Pull".

For Linux/Unix/OSX: change into the folder with the files and execute

hg pull 
hg up -c

and then you can continue from step 3 above.

Extra perk - Build the latest Hugin

If you're already here, you may want to also build and enjoy the latest Hugin. Some of the current contributors to the build, distribution and code of Hugin have learned this way. You are just a few clicks away from building your own bleeding edge Hugin. Find your platform in Build your Own Test Builds section of the wiki and follow the instructions.

Welcome to the club!

Translation guide for specific terms

Note to translators, please add your language variant to the term on a new line in the same format as NL=
Also add your own difficult terms that are not mentioned here.

Note to developers, please check and enhance the meanings of these terms if they are unclear or incorrect.

Aligning versus Finding control points: Problem= they appear to be similar or the same, can they be interchanged?

Anchor: Meaning=Reference; NL=referentie (was anker)

bundle: Meaning=A technique for distributing OS X software as a single file.; NL=bundle (bundel?)

bundled version: Meaning=? Any packaged software will contain multiple files, these files are said to be 'bundled' (not just OS X); NL=ingebouwde versie (gebundelde versie?)

button: DE=Schaltfläche

Camera response (C. r. curve): Meaning=it corresponds with photo-electrical transfer function, and I am not sure can I translate it to "opto-electic curve of camera" in my language, because stright tranlation of "camera response" statement sounds trivial and not clear.; PL=krzywa optoelektryczna aparatu?

control points: Meaning=corresponding areas in two images (or the same image for horizontal and vertical control points); ET=juhtpunktid; NL=ijkpunten (was controle punten), IJkpunten bij hoofdletters

Crop factor: Meaning=The physical size of a CCD sensor relative to a 35mm frame.

Cropped (images): Meaning=image cut smaller than the original size; Discussion=Should this be translated? Like Blend, this is jargon, may be clearer when untranslated?; ET=kärbitud (pildid); NL=uitgesneden (afbeeldingen)

Custom parameters: Meaning=parameters other than standard (+context???); NL=aangepaste parameters

Estimate (position, FoV, etc.): Meaning=? in my book, estimate means an educated guess. I get the impression that a more exact term is intended for hugin. Where can this term be replaced with "calculate" or "determine"?; ET=määratlema; NL=bepalen (eng:determine), bereken (eng:calculate) alternative suggestion: Schatten (eng:estimate)

Exposure blending (or Exposure fusion): Meaning=Taking a bracketed photo stack and picking the best bits to create a new image. Hugin tries to use the phrase 'Exposure fusion' rather than 'blending' as the tool for this is enfuse.; NL=Belichtings lagen samenvoegen (Note: enblend = samenvoegen; enfuse = belichtings lagen samenvoegen?)

Field of View: Meaning=Horizontal Angle of view; ET=vaateväli; NL=beeldhoek

flatfield: Meaning=An astronomical technique, using a photo taken with the lens covered or of an even white surface to calibrate normal photos; NL=flatfield (astrofoto jargon, ook in NL gebruikt)

flatfile: Meaning=?; NL=?

grayscale: Meaning=monochrome colourspace. Typically grayscale images can have many shades of gray as well as black and white.; ET=halltoonid; NL=grijsschaal (kan beter!)

High Dynamic Range (HDR): Meaning=Luminance values are within a large numeric range (typically floating point with a linear response); NL=Hoog Dynamisch Bereik (HDR)

image: Meaning=photo, scan, ....; ET=pilt; NL=afbeelding; DE=Bild

keypoint: Meaning=; DE=Merkmalspunkt (see Article about SIFT in the German Wikipedia)

Low Dynamic Range (LDR): Meaning=Luminance values are within a small numeric range (typically 8-bit or 16bit integer with a non-linear response curve).; NL=Laag Dynamisch Bereik (LDR)

mapping: Meaning=render and distort an image to a different projection?; NL=translatie, afbeelding, vervorming, projectie?

Num. Transf.: Meaning=Numerical Transform. Rotation of panorama roll, pitch and yaw by manually entering numbers.; NL=Num. Transf.

Photometric Alignment: Meaning=Determining relative exposure, camera response and vignetting; ET=fotomeetriline joondamine; NL=fotometrische uitlijning (beter?: fotometrische afstemming)

Photometric Optimisation: Meaning=Optimisation of non-mapping image parameters, such as 'Camera response', Vignetting and Exposure.; ET=fotomeetriline optimeerimine; NL=fotometrische optimalisatie

pyramid image: Meaning=This is the practice of creating a stack of successively smaller versions of an image, useful for many image manipulation tasks.; NL=piramidale afbeelding

Seam blending: Meaning=Taking two or more partially overlapping photos and blending then with a seam down the middle of the overlap. The tool typically used for this is enblend

Stitcher (the tab): Meaning= Where the actual combining of the images is done; ET=Ühendaja; NL=Samenvoegen (alt: Combineren, Naaien?)

Vertical or Horizontal guide: Meaning=Horizontal or Vertical "control points"; NL=h/v hulp (suggestie: ijklijnen)?

Do not translate:

Autopano (program name)
Autopano-SIFT (program name)
Deflate (zip method)
Enblend (program name)
EXR (HDR file type)
JPEG (file type)
LZW (zip method)
Nona (program name)
Packbits (zip method)
PTStitcher (program name)

Technical translation issues

Some strings don't appear to be translated, they are apparently generated by the GUI toolkit or the operating system. Most likely they will be in the same language as hugin, because very few people, other than translators, start a program with a specific language other than that of the environment.

The file src/translations/ignored-entries.txt contains a list of ignored entries from the xrc files (which are used to declare most of the hugin UI). If you need to translate a sentence which is there, remove the line from the file and run the extract-messages.sh script to update the .po files.

If you find a source term that isn't correct, spelling or meaning, probably best to bring it up with Pablo d'Angelo or on the hugin mailinglist: [1]

List of source string problems

calculate highest sensible width. (uses every image pixel)

I can translate this literally, but is this even helpful in English? (this is a tooltip for the size calc button in the Stitcher tab)

Tips and Tricks

Running hugin in a specific language

If you want to run hugin in another language than the default, use the following command (Linux with UTF8):

$ LANG=nl_NL.utf8 hugin

This will start hugin in dutch. Other languages have different names of course, try looking in /usr/share/i18n/locales/.

Developer info

Adding new strings

After adding new strings, translators need to find them in the .pot and .po files otherwise they won't get translated.

Hugin has a script to extract the messages from both the .xrc files and the .cpp source code and insert them into the hugin.pot and .po files. New strings are added and unused strings are marked as obsolete.

Before running the script, make sure you have wxrc installed. On older Ubuntu, run sudo apt-get install wxrc. On Ubuntu 10.4 it is sudo apt-get install wx-common.

Then, add the new strings:

hg pull
hg up
cd src/translations
./extract-messages.sh
hg ci
hg push ssh://YOUR-SOURCEFORGE-USERNAME@hugin.hg.sourceforge.net/hgroot/hugin/hugin

Applying a contributed .po file

You could just overwrite the original and commit, but this assumes the file is correctly formatted and hasn't lost any strings. Better to use msgmerge to merge the contributed .po file with the existing. Hugin has a script to test what will happen. Use msgfmt for a quick sanity check too:

 src/translations/diff_po.pl src/translations/zh_CN.po /tmp/zh_CN.contributed.po
 msgmerge -o zh_CN.merged.po /tmp/zh_CN.contributed.po src/translations/zh_CN.po
 msgfmt -c --statistics zh_CN.merged.po
 msgfmt -c --statistics src/translations/zh_CN.po
 mv zh_CN.merged.po src/translations/zh_CN.po
 hg ci zh_CN.po -m 'Edited chinese translation'
 hg push ssh://YOUR-SOURCEFORGE-USERNAME@hugin.hg.sourceforge.net/hgroot/hugin/hugin

Statistics

msgfmt --statistics eo_XX.po

Issues That Need Work

There are more than 1000 strings in the hugin.pot file. The main translation problem we have now is that many of these strings are in the sourcecode, but not in bits that are used - i.e. there are strings that are being translated unnecessarily (the panodruid for example).
The .po files headers are inconsistent. Ideally they would all feature the same license and copyright notice; and they would list all contributors.

Website / Release Notes

Some translators contribute also translated release notes. These are published on the web at http://hugin.sourceforge.net/releases/ . Usually the release manager will draft the release notes in English early on in the release process. Even if they are not linked, you can find them in the repository at http://hugin.hg.sourceforge.net/hgweb/hugin/hugin-web/file/tip/releases

Important: make sure you translate the file from the repository and not the resulting file displayed on the web, e.g. for 2012.0.0 translate the raw version of http://hugin.hg.sourceforge.net/hgweb/hugin/hugin-web/file/4894a12dc2ea/releases/2012.0.0/en.shtml and not the current one from http://hugin.sourceforge.net/releases/ - the former is the source for the page while the latter is the resulting page after server side includes and other server side transformations.

Thanks for your contributions!