diff tools/po4a/po4a-translate @ 722:082bb76417f1

Add Po4a 0.37-dev(2009-03-08)

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/tools/po4a/po4a-translate	Thu Mar 12 15:43:56 2009 +0800
@@ -0,0 +1,257 @@
+#! /usr/bin/env perl
+eval 'exec perl -S $0 ${1+"$@"}'
+    if $running_under_some_shell;
+
+# po4a-translate -- translate doc files using a message catalog(ie, po file)
+# $Id: po4a-translate,v 1.41 2009-03-07 12:33:10 nekral-guest Exp $
+#
+# Copyright 2002, 2003, 2004 by Martin Quinson (mquinson#debian.org)
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of GPL (see COPYING).
+
+=head1 NAME
+
+po4a-translate - convert a po file back to documentation format
+
+=head1 SYNOPSIS
+
+po4a-translate -f E<lt>fmtE<gt> -m E<lt>master.docE<gt> -p E<lt>XX.poE<gt> -l E<lt>XX.docE<gt>
+
+(XX.doc is the output, all others are inputs)
+
+=head1 DESCRIPTION
+
+The po4a (po for anything) project goal is to ease translations (and more
+interestingly, the maintenance of translations) using gettext tools on
+areas where they were not expected like documentation.
+
+The C<po4a-translate> script is in charge of converting the translation
+(which was done in a po file) under the documentation format back. The
+provided C<po> file should be the translation of the C<pot> file which were
+produced by po4a-gettextize(1).
+
+=head1 OPTIONS
+
+=over 4
+
+=item -f, --format
+
+Format of the documentation you want to handle. Use the --help-format
+option to see the list of available formats.
+
+=item -a, --addendum
+
+Add a file to the resulting file (to put translator's name or a section
+"About this translation", for example). The first line of the file to insert
+should be a PO4A header indicating where it should be added (see section
+I<HOWTO add extra text to translations> in po4a(7)).
+
+=item -A, --addendum-charset
+
+Charset of the addenda. Note that all the addenda should be in the same
+charset.
+
+=item -m, --master
+
+File containing the master document to translate.
+
+=item -M, --master-charset
+
+Charset of the file containing the document to translate.
+
+=item -l, --localized
+
+File where the localized (translated) document should be written.
+
+=item -L, --localized-charset
+
+Charset of the file containing the localized document.
+
+=item -p, --po
+
+File from which the message catalog should be read.
+
+=item -o, --option
+
+Extra option(s) to pass to the format plugin. Specify each option in the
+'name=value' format. See the documentation of each plugin for more
+information about the valid options and their meanings.
+
+=item -k, --keep
+
+Minimal threshold for translation percentage to keep (ie, write) the
+resulting file (default: 80). Ie, by default, files have to be translated
+at at least 80% to get written.
+
+=item -w, --width
+
+Column at which we should wrap the resulting file.
+
+=item -h, --help
+
+Show a short help message.
+
+=item --help-format
+
+List the documentation format understood by po4a.
+
+=item -V, --version
+
+Display the version of the script and exit.
+
+=item -v, --verbose
+
+Increase the verbosity of the program.
+
+=item -d, --debug
+
+Output some debugging information.
+
+=back
+
+=head1 Adding content (beside translations) to generated files
+
+To add some extra content to the generated document beside what you
+translated (like the name of the translator, or a "about this translation"
+section), you should use the C<--addendum> option. 
+
+The first line of the addendum must be a header indicating where to put
+it in the document (it can be before or after a given part of the
+document).  The rest of the file will be added verbatim to the resulting
+file without further processing.
+
+Note that if po4a-translate fails to add one of the given files, it discards
+the whole translation (because the missing file could be the one indicating
+the author, what would prevent the users to contact him to report bugs in
+the translation).
+
+The header has a pretty rigid syntax. For more information on how to use
+this feature and how it works, please refer to the po4a(7) man page.
+
+=head1 SEE ALSO
+
+L<po4a(7)>, L<po4a-gettextize(1)>, L<po4a-updatepo(1)>, L<po4a-normalize(1)>.
+
+
+=head1 AUTHORS
+
+ Denis Barbier <[e-mail]>
+ Martin Quinson (mquinson#debian.org)
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2002, 2003, 2004 by SPI, inc.
+
+This program is free software; you may redistribute it and/or modify it
+under the terms of GPL (see the COPYING file).
+
+=cut
+
+use 5.006;
+use strict;
+use warnings;
+
+use Locale::Po4a::Chooser;
+use Locale::Po4a::TransTractor;
+use Locale::Po4a::Common;
+
+use Pod::Usage qw(pod2usage);
+use Getopt::Long qw(GetOptions);
+
+Locale::Po4a::Common::textdomain("po4a");
+
+sub show_version {
+    Locale::Po4a::Common::show_version("po4a-translate");
+    exit 0;
+}
+
+
+Getopt::Long::Configure('no_auto_abbrev','no_ignore_case');
+my ($outfile,$width,$threshold)=('-',80,80);
+my ($help,$help_fmt,@verbose,$debug,@addfiles,$format,@options);
+my ($master_filename,$po_filename);
+my ($mastchar,$locchar,$addchar);
+GetOptions(
+	'help|h'        => \$help,
+	'help-format'   => \$help_fmt,
+
+	'master|m=s'    => \$master_filename,
+	'localized|l=s' => \$outfile,
+	'po|p=s'        => \$po_filename,
+	'addendum|a=s'  => \@addfiles,
+	'format|f=s'    => \$format,
+
+	'master-charset|M=s'    => \$mastchar,
+	'localized-charset|L=s' => \$locchar,
+	'addendum-charset|A=s' => \$addchar,
+
+	'option|o=s'    => \@options,
+
+	'width|w=s'     => \$width,
+	'verbose|v'     => \@verbose,
+	'debug|d'       => \$debug,
+	'keep|k=s'      => \$threshold,
+
+	'version|V'     => \&show_version
+) or pod2usage();
+
+$help && pod2usage(-verbose => 1, -exitval => 0);
+$help_fmt && Locale::Po4a::Chooser::list(0);
+
+(defined($master_filename) && length($master_filename))||pod2usage();
+(defined($po_filename)     && length($po_filename))    ||pod2usage();
+-e $master_filename || die wrap_msg(gettext("File %s does not exist."), $master_filename);
+-e $po_filename || die wrap_msg(gettext("File %s does not exist."), $po_filename);
+
+my (@pos,@masters);
+push @pos,$po_filename;
+push @masters,$master_filename;
+
+my %options = (
+    "verbose" => scalar @verbose,
+    "debug" => $debug);
+
+foreach (@options) {
+    if (m/^([^=]*)=(.*)$/) {
+	$options{$1}="$2";
+    } else {
+	$options{$_}=1;
+    }
+}
+# parser
+my $doc=Locale::Po4a::Chooser::new($format,%options);
+
+
+# Prepare the document to be used as translator, but not parser
+$doc->process('po_in_name'       => \@pos,
+	      'file_in_name'     => \@masters,
+	      'file_in_charset'  => $mastchar,
+	      'file_out_charset' => $locchar,
+	      'addendum_charset' => $addchar);
+
+my ($percent,$hit,$queries) = $doc->stats();
+my $error=0;
+
+print STDERR wrap_msg(gettext("%s is %s%% translated (%s of %s strings)."),
+    $master_filename, $percent, $hit, $queries)
+  if (scalar @verbose) && ($percent>=$threshold);
+
+
+if ($percent<$threshold)  {
+    print STDERR wrap_msg(gettext("Discard the translation of %s (only %s%% translated; need %s%%)."),
+	$master_filename, $percent, $threshold);
+    unlink($outfile) if (-e $outfile);
+} else {
+    foreach my $add (@addfiles) {
+	unless ($doc->addendum($add)) {
+	    unlink($outfile) if (-e $outfile);
+	    die wrap_msg(gettext("Discard the translation of %s (addendum %s does not apply)."),
+		$master_filename, $add);
+	}
+    }
+    $doc->write($outfile);
+}
+
+1;
+