wiki:TranslationIntro
Last modified 19 months ago Last modified on 09/24/12 04:24:19

See also http://www.perlfoundation.org/perl5/index.cgi?localization

to see the current status visit this page http://perlide.org/translations/

Short introductory guide to translating (localizing) Padre

There are several thing that can and should be translated. They will be described on this page

  • The GUI of Padre
  • Plug-ins
  • Perl 5 diagnostics
  • Perl 5 documentation (perldoc in general)
  • Perl 5 call-tips
  • Similar things for other languages

Translating the GUI of Padre

The following is intended for people who work on unix-ish operating systems and have no fear for the command line.

But even If you do not belong to that group you have no excuse for not contributing a translation since you may use Poedit. Poedit is a graphical tool that supports extraction and translation of messages and runs on a variety of platforms including MS Windows (see lower).

If you chose to work on the command line the following is a short intro which describes the steps I took. It does not cover all features of the tools used - please refer to the fine manuals of the respective program.

Before you begin, please make sure that you have the GNU gettext utilities installed and svn as well (if not using TortoiseSVN e.g.) On Ubuntu - install like this:

sudo aptitude install gettext
sudo aptitude install subversion

Translations during a release branch

If you are doing the translation during the release freeze then will need to check out the relevant release branch and work only in that branch!

To switch between trunk and the release branch:

svn switch http://svn.perlide.org/padre/branches/Padre-x.xx

Where x.xx follows the Padre versioning, for the current release x.xx would be 0.88.

Once you have committed your updates to switch back to trunk:

svn switch http://svn.perlide.org/padre/trunk/Padre

For further details see Release

Translating Padre from trunk

You can translate Padre any time you like, often it's simplest from trunk.

  1. Check out the current sources of Padre from the subversion repository: http://svn.perlide.org/padre/trunk/
    svn co http://svn.perlide.org/padre/trunk/ padre
    
  1. You do NOT need to update the messages.pot file any more as it is being done regularly via cron-job.
  1. Change into the directory 'Padre/share/locale'
    1. In case of updating an already existing language execute
      msgmerge -o <lng>.po.new <lng>.po messages.pot
      
      This will merge the already existing translations and the new template file, resulting in a new file that you now need to edit. Be careful to check the already existing translations: The merging might produce wrong results.
    2. In case of creating a totally new translation execute
      msginit -i messages.pot -o <lng>.po -l <lng_CC>
      
      Where <lng_CC> is the locale id with language and country ids. Eg.: de_DE or en_US.
  2. Add new files to the repository or - if you don't have write access - either send the updated "messages.pot" and the .po file to the padre development mailing list or open a new ticket and attach the files to it.
perl ../tools/po_stats.pl

Will create a textual report on the status of all the existing translation files. Remember to run this under the 'Padre' subdirectory.

MS Windows

For MS Windows Download the Complete package, except sources from http://gnuwin32.sourceforge.net/packages/gettext.htm and install it to c:/Program Files/GnuWin32/ (currently we hard coded that path into dev but it can be fixed of course)

Adding a translation

  1. Check out the list of existing translations: http://svn.perlide.org/padre/trunk/Padre/share/locale/
  2. Create the .po file and add it to SVN (note: only the .po file, not the .mo one).
  3. Change lib/Padre/Locale.pm (the %SHORTNAME hash and the 'menu_view_languages' subroutine )
  4. Update the Changes file to brag about this new translation! :-)

Poedit

The command line instructions do still apply. Poedit, as a graphical editor for the po-files, aims to provide a more convenient approach to editing catalogs than launching vi and editing the file by hand.

First you need to install the package. On Gnu/Linux?, poedit is probably already included in your distribution (e.g. on Debian/Ubuntu?, do "sudo apt-get install poedit"). For other Operating Systems (including MS Windows and Apple OS X) you'll find binaties at the Poedit download page. Follow the instructions to edit translations:

  1. Open poedit.

  1. Go to File-Open and select the desired translation (.po file). On *n*x systems the po files for Padre itself (not the plugins) can be found at trunk/Padre/share/locale.

  1. Go to Catalogue-Update from POT file. Choose the file messages.pot on the same location as above (generated by the command line instructions).

  1. Click OK.

  1. The missing, fuzzy and correct translation will be showed in different colours.

  1. Check in the .po file you edited (go to the .po files directory and do svn ci <language code>.po -m "Update to <language> translation").

Plug-ins

Since Padre 0.34, the plugin API has been updated to allow plugin translation.

There is indeed a new method plugin_locale_directory() that your plugin can implement. It should return a directory where Padre can find the *.mo files for your plugin. This directory will then be added to the locale search path.

Note that you are not forced to implement plugin_locale_directory(), since it defaults to $sharedir/locale (with $sharedir as defined by File::ShareDir), and thus should work as is for your plugin if you're using the install_share command of Module::Install .

Once this is done, you need to extract the strings to be translated (see above) to a messages.pot file in your plugin locale directory (yes, the same directory you're advertising with the plugin_locale_directory() method).

Then, it's translation business as usual, with one minor change: the *.po (and thus the *.mo too) files should be named $plugin-$locale.po instead of just $locale.po. That is, the german translation of Padre::Plugin::Vi should be named Vi-de.po.

Don't forget to generate the *.mo files before the release, and to include them in the dist tarball. For the plugins using Module::Build, replacing my $builder = Module::Builder->new with the following is quite handy:

my $class = Module::Build->subclass(
    class => "Module::Build::Custom",
    code => <<'SUBCLASS' );

sub ACTION_build {
    my $self = shift;

    my $msgfmt = $^O =~ /(linux|bsd)/
        ? `which msgfmt`
        : "c:/Program Files/GnuWin32/bin/msgfmt.exe";
    chomp $msgfmt;
    if ( $msgfmt && -e $msgfmt ) {
        my @pofiles = glob "lib/Padre/Plugin/SpellCheck/share/locale/*.po";
        foreach my $pof ( @pofiles ) {
                my $mof = $pof;
                $mof =~ s/\.po$/.mo/;
                $self->do_system( "$msgfmt -o $mof $pof" );
        }
    }
    $self->SUPER::ACTION_build;
}

SUBCLASS


my $builder = $class->new(

It will generate the *.mo files from the *.po files when issuing the ./Build command.

So, to summarize:

  1. implement plugin_locale_directory() (or not if the default suits your needs)
  2. create the locale directory (if necessary) share/locale
  3. use Wx::gettext() everywhere instead of plain text
  4. extract those messages in a messages.pot file by running {{{../tools/update_pot_file.pl}}
  5. create a $plugin-$locale.po file in your plugin locale directory and translate it - or ask the translators to do it
  6. upon releasing, create the *.mo files and ship them with your plugin
  7. tada! your plugin is now translated...

Perl 5 diagnostics

We have an integration with translated versions of the perldiag.pod that comes with perl. ( http://perldoc.perl.org/perldiag.html ) Currently we only found French translation on POD2::FR (http://search.cpan.org/dist/POD2-FR).

If someone wants to have translation to any language, the right way is to start translating the perldiag.pod file of perl 5.10 and releasing it as POD2::XY Where XY is the language code.

Actually even the English version of perldiag.pod could get some improvement. The problem with it as it is with a large part of the Perl 5 documentation is that in many places it assumes prior knowledge of C or UNIX. Also in many cases it "correct but not too helpful for beginners".

e.g.

Global symbol "%s" requires explicit package name

(F) You’ve said "use strict" or "use strict vars", which indicates that all variables
must either be lexically scoped (using "my" or "state"), declared
beforehand using "our", or explicitly qualified to say which package 
the global variable is in (using "::").

A beginner probably needs something like this:

You have forgotten to declare the variable using "my" or it was declared in
another scope or it has a typo.

So the "translations" don't necessarily have to be exact translations of the English version but should be good explanations for people with not much background in Perl.

See also #169

As the content of perldiag is huge it is better to start with the most common warnings and errors. For now see the list here: http://www.perlmonks.org/?node_id=733201 (TODO: and later maybe copy that list here) (TODO: provide examples scripts generating each one of the important errors/warnings)

http://mail.perlide.org/pipermail/padre-dev/2008-December/000368.html

Checking Translation Files

msgfmt -c -o /dev/null PO_FILE

Perl 5 documentation (perldoc in general)

Could be translated and uploaded to CPAN as POD2::XY. We have not implemented it but we should provide and indexed access to the selected translated version of the documentation.

There are several modules on CPAN in the POD2:: name space and there is the

See also http://perldoc2.sourceforge.net/

Perl 5 call-tips

The source of the call-tips is in http://svn.perlide.org/padre/trunk/Padre/share/languages/perl5/perl5.yml We have not thought of a way how to translate these. (and even the English version needs improvement)

Similar things for other languages

We have not thought about this yet.

Credits

We would like to make sure the translators get their special credit in both the Padre source code and on the Padre web site both in English and in their own languages.

So if you are are translator

  1. Add yourself to lib/Padre.pm that will appear on http://search.cpan.org/dist/Padre/lib/Padre.pm#Translators
  2. Add yourself to lib/Padre/Wx/About.pm that will be visible when pressing Help/About/Translators?
  3. Check out the source of the web site svn co http://svn.perlide.org/padre/trunk/template.padre.perlide.org/
  4. For the English text on the developers page
    1. Create a file with your nickname in the data/developers/ directory. There are already several files there so you can look at their content to understand waht to write there.
    2. In addition edit the data/stash.yml file and add your nick to the developers: section at the bottom of the file.
  5. For the special translators page
    1. Create a file in the data/translators/ directory
    2. Add your nick to the data/stash.yml file in the translators section at the bottom of the file

A few seconds after you commit the files the new content should appear on the Padre web site.

If you need help with any of these, please ask on our IRC channel or on the padre-dev mailing list.

Attachments