Name

       Dist::Zilla::Plugin::LocaleTextDomain - Compile Local::TextDomain language files

Synopsis

       In dist.ini:

         [ShareDir]
         [LocaleTextDomain]
         textdomain = My-App
         lang_dir = po
         share_dir = share

Description

       This plugin compiles GNU gettext language files and adds them into the distribution for
       use by Locale::TextDomain. This is useful if your distribution maintains gettext language
       files in a directory, with each file named for a language. The plugin uses "msgfmt" to
       compile each file and then adds it to the distribution's share directory. You can then use
       the ShareDir plugin to make sure it gets installed in the right place.

   Installation
       By default, Locale::TextDomain searches for language files in the shared directory for
       your distribution, as defined by File::ShareDir. Prior to v1.21, however, this was not the
       case. Instead, it searched for files in Perl's @INC directories. If you're stuck with one
       of these older versions of Locale::TextDomain, you'll have to install the compiled
       language files into the lib directory in your distribution. To do so, simply set the
       "share_dir" attribute to "lib":

         [LocaleTextDomain]
         textdomain = My-App
         lang_dir = po
         share_dir = lib

       If your distribution uses ExtUtils::MakeMaker to do the installation, the files will now
       be installed in the proper location. If it relies on Module::Build, you will have to do a
       bit of additional work. First, subclass Module::Build by creating
       inc/Module/Build/MyApp.pm with this code:

         package Module::Build::MyApp;
         use parent 'Module::Build';

         sub new {
             my ( $class, %p ) = @_;
             my $self = $class->SUPER::new(%p);
             $self->add_build_element('mo');
             return $self;
         }

       Then tell Dist::Zilla to use the subclass via the "mb_class" attribute in dist.ini:

         [ModuleBuild]
         mb_class = Module::Build::MyApp

       Now the .mo files will be installed where Locale::TextDomain can find them.

   Configuration
       Configuration attributes settable in dist.ini to change the plugin behavior.

       "textdomain"

       The textdomain to use for your language files, as defined by the Locale::TextDomain
       documentation. This should be the same value declared in each use of Locale::TextDomain in
       your module. For example, if such lines look like this:

         use LocaleText::Domain qw(com.example.myApp);

       Then set it to such in your dist.ini

         [LocaleTextDomain]
         textdomain = com.example.myApp

       Defaults to the name of your distribution, which is the value that Locale::TextDomain
       recommends you use.

       "lang_dir"

       The directory containing your language files. Defaults to po.

       "share_dir"

       The name of the distribution directory into which compiled language files should be added.
       Defaults to "share".

       "msgfmt"

       The location of the "msgfmt" program, which is distributed with GNU gettext
       <http://www.gnu.org/software/gettext/>. Defaults to just "msgfmt", which should work if
       it's in your path.

       "language"

       A language to be compiled. May be specified more than once. If not specified, the default
       will be the list of files in "lang_dir" ending in "lange_file_suffix".

       "lang_file_suffix"

       Suffix used in the language file names. These are the files your translators maintain in
       your repository. Defaults to "po".

       "bin_file_suffix"

       Suffix to use for the compiled language file. Defaults to "mo".

       "finder"

       File finders to use to look for files to search for strings to extract. May be specified
       more than once. If not specified, the default will be ":InstallModules" and ":ExecFiles";
       that is, files below lib/ and executable files marked by e.g. the "ExecDir" plugin. You
       can also combine default finders with custom ones based on a "FileFinder" plugin. For
       example:

         [FileFinder::ByName / MyFiles]
         file = *.pl

         [LocaleTextDomain]
         finder = MyFiles
         finder = :ShareFiles

       This configuration will extract strings from files that match "*.pl" and all files in a
       share directory.

       "xgettext_args"

       Extra arguments to be passed to the extractor program. This is an advanced feature that
       exists for cases where special customization is needed, such as when different keywords
       are used to mark strings.

       "override_args"

       By default, arguments are passed to the extractor that set the language to "perl" as well
       as set keywords that tell xgettext how strings are marked (which includes the keywords
       specified by Locale::TextDomain). If for some reason you don't want that (presumably
       because you're going to use the "xgettext_args" attribute to configure your own language
       and keywords), then you can set this attribute to true.

       "join_existing"

       If you have strings in files other than Perl files, you can cause the extractor to be
       invoked multiple times against different sets of files with different arguments. The
       strings from all of these other file sets will be joined into your "po" files.

       For example, imagine you have a GTK+ app. You have strings in your Perl modules, as usual,
       but perhaps you also have strings in your Glade files that you want to be translatable.
       You could write something like this into your dist.ini:

         [FileFinder::ByName / GladeFiles]
         file = *.ui

         [LocaleTextDomain]
         join_existing = --language=glade %{GladeFiles}f

       The value of the "join_existing" attribute is the argument list that will be passed to an
       additional invocation of xgettext. The "%{GladeFiles}f" syntax allows you to use a finder
       to search for files to be passed to the extractor, but you could also "hard code" one or
       more files as well.

       This attribute is repeatable. If your project also had a JavaScript file with strings, you
       could just add another line to your "LocaleTextDomain" section:

         join_existing = -L javascript share/media/app.js

Author

       David E. Wheeler <david@justatheory.com>

Contributor

       Charles McGarvey <ccm@cpan.org>

Copyright and License

       This software is copyright (c) 2012-2017 by David E. Wheeler.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.