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