path: root/lib/Locale/POFileManager.pm

package Locale::POFileManager;
use Moose 0.90;
use MooseX::Types::Path::Class qw(Dir);
use Scalar::Util qw(reftype weaken);
# ABSTRACT: Helpers for keeping a set of related .po files in sync

=head1 SYNOPSIS

  use Locale::POFileManager;

  my $manager = Locale::POFileManager->new(
      base_dir           => '/path/to/app/i18n/po',
      canonical_language => 'en',
  );

  my %missing = $manager->find_missing;
  $manager->add_stubs;
  $manager->add_language('de');

=head1 DESCRIPTION

This module contains helpers for managing a set of gettext translation files,
including tools to keep the translation files in sync, adding new translation
files, and manipulating the translations contained in the files. It is based on
the L<Locale::Maketext::Lexicon> parser library.

=cut

=method new

Accepts a hash of arguments:

=over 4

=item base_dir

The directory that contains the .po files. Required.

=item canonical_language

The language for the file that contains the canonical set of msgids. Required.

=item stub_msgstr

The msgstr to insert when adding stubs to language files. This can be either a
literal string, or a coderef which accepts a hash containing the keys C<msgid>,
C<lang>, and C<canonical_msgstr> (the msgstr value from the
C<canonical_language>. Optional.

=back

=method base_dir

Returns a L<Path::Class::Dir> object corresponding to the C<base_dir> passed to
the constructor.

=cut

has base_dir => (
    is       => 'ro',
    isa      => Dir,
    required => 1,
    coerce   => 1,
);

=method files

Returns a list of L<Locale::POFileManager::File> objects corresponding to the
.po files that were found in the C<base_dir>.

=cut

has files => (
    traits     => [qw(Array)],
    isa        => 'ArrayRef[Locale::POFileManager::File]',
    lazy       => 1,
    builder    => '_build_files',
    init_arg   => undef,
    handles    => {
        files       => 'elements',
        _first_file => 'first',
        _add_file   => 'push',
    },
);

sub _build_files {
    my $self = shift;
    my $dir = $self->base_dir;

    require Locale::POFileManager::File;

    my @files;
    for my $file ($dir->children) {
        next if     $file->is_dir;
        next unless $file->stringify =~ /\.po$/;
        my $msgstr = $self->stub_msgstr;
        push @files, Locale::POFileManager::File->new(
            file  => $file,
            defined($msgstr) ? (stub_msgstr => $msgstr) : (),
        );
    }

    return \@files;
}

=method canonical_language

Returns the canonical language id passed to the constructor.

=cut

has canonical_language => (
    is       => 'ro',
    isa      => 'Str',
    required => 1, # TODO: make this not required at some point?
);

has _stub_msgstr => (
    is       => 'ro',
    isa      => 'Str|CodeRef',
    init_arg => 'stub_msgstr',
);

sub BUILD {
    my $self = shift;

    confess("Canonical language file must exist")
        unless $self->has_language($self->canonical_language);
}

=method stub_msgstr

Returns the string passed to the constructor as C<stub_msgstr> if it was a
string, or a coderef wrapped to supply the C<canonical_msgstr> option if it was
a coderef.

=cut

sub stub_msgstr {
    my $self = shift;
    my $msgstr = $self->_stub_msgstr;
    return unless defined($msgstr);
    return $msgstr if !reftype($msgstr);
    my $weakself = $self;
    weaken($weakself);
    return sub {
        my %args = @_;
        my $canonical_msgstr;
        $canonical_msgstr =
            $weakself->canonical_language_file->msgstr($args{msgid})
                if $weakself;
        return $msgstr->(
            %args,
            defined($canonical_msgstr) ? (canonical_msgstr => $canonical_msgstr) : (),
        );
    }
}

=method has_language

Returns true if a language file exists for the given language in the
C<base_dir>, false otherwise.

=cut

sub has_language {
    my $self = shift;
    my ($lang) = @_;

    for my $file ($self->files) {
        return 1 if $file->language eq $lang;
    }

    return;
}

=method add_language

Creates a new language file for the language passed in as an argument. Creates
a header for that file copied over from the header in the C<canonical_language>
language file, and saves the newly created file in the C<base_dir>.

=cut

sub add_language {
    my $self = shift;
    my ($lang) = @_;

    return if $self->has_language($lang);

    my $file = $self->base_dir->file("$lang.po");
    confess("Can't overwrite existing language file for $lang")
        if -e $file->stringify;

    my $canon_pofile = $self->canonical_language_file;

    my $fh = $file->openw;
    $fh->binmode(':utf8');
    $fh->print(qq{msgid ""\n});
    $fh->print(qq{msgstr ""\n});
    for my $header_key ($canon_pofile->headers) {
        $fh->print(qq{"$header_key: }
                 . $canon_pofile->header($header_key)
                 . qq{\\n"\n});
    }
    $fh->print(qq{\n});
    $fh->close;

    my $msgstr = $self->stub_msgstr;
    my $pofile = Locale::POFileManager::File->new(
        file => $file,
        defined($msgstr) ? (stub_msgstr => $msgstr) : (),
    );


    $self->_add_file($pofile);
}

=method language_file

Returns the L<Locale::POFileManager::File> object corresponding to the given
language.

=cut

sub language_file {
    my $self = shift;
    my ($lang) = @_;

    return $self->_first_file(sub {
        $_->language eq $lang;
    });
}

=method canonical_language_file

Returns the L<Locale::POFileManager::File> object corresponding to the
C<canonical_language>.

=cut

sub canonical_language_file {
    my $self = shift;
    return $self->language_file($self->canonical_language);
}

=method find_missing

Searches through all of the files in the C<base_dir>, and returns a hash
mapping language names to an arrayref of msgids that were found in the
C<canonical_language> file but not in the file for that language.

=cut

sub find_missing {
    my $self = shift;
    my $canon_file = $self->canonical_language_file;

    my %ret;
    for my $file ($self->files) {
        $ret{$file->language} = [$file->find_missing_from($canon_file)];
    }

    return %ret;
}

=method add_stubs

Adds stub msgid (and possibly msgstr, if the C<stub_msgstr> option was given)
entries to each language file for each msgid found in the C<canonical_language>
file but not in the language file.

=cut

sub add_stubs {
    my $self = shift;
    my $canon_file = $self->canonical_language_file;

    for my $file ($self->files) {
        $file->add_stubs_from($canon_file);
    }
}

__PACKAGE__->meta->make_immutable;
no Moose;

=head1 BUGS

No known bugs.

Please report any bugs through RT: email
C<bug-locale-pofilemanager at rt.cpan.org>, or browse to
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Locale-POFileManager>.

=head1 SEE ALSO

L<Locale::Maketext::Lexicon>

L<Locale::Maketext>

L<Locale::PO>

=head1 SUPPORT

You can find this documentation for this module with the perldoc command.

    perldoc Locale::POFileManager

You can also look for information at:

=over 4

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Locale-POFileManager>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Locale-POFileManager>

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Locale-POFileManager>

=item * Search CPAN

L<http://search.cpan.org/dist/Locale-POFileManager>

=back

=begin Pod::Coverage

BUILD

=end Pod::Coverage

=cut

1;