Dist::...tDomain(3pm)

💖 Dist::Zilla::Plugin::LocaleTextDomain 💖

okay bestie, so this page is the manual for Dist::Zilla::Plugin::LocaleTextDomain (from the User Contributed Perl Documentation, no less 👑), and it's literally all about compiling Local::TextDomain language files. Let's get into it 💅

---

✨ 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

that's it, that's the whole vibe check ✨

---

🦋 DESCRIPTION 🦋

okay so here's the tea ☕: this plugin compiles GNU gettext language files and adds them into your distribution so Locale::TextDomain can use them. Super useful if your distribution keeps 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. Then you can use the ShareDir plugin to make sure it gets installed in the right place. iconic behavior, honestly 💖

🧚 Installation 🧚

By default, Locale::TextDomain searches for language files in the shared directory for your distribution, as defined by File::ShareDir. But — and this is the plot twist 😭 — prior to v1.21, that was not the case. Instead, it searched for files in Perl's @INC directories. So 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. slay 🫶

💜 Configuration 💜

Configuration attributes settable in dist.ini to change the plugin behavior. Let's go one by one, bestie, no skips 🎀

• 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.

---

and that's the whole page, bestie, you ate it up ✨💅 tiny little sign-off for the road: this was written up against perl v5.26.2 and dated 2018-07-08 — periodt, go compile some language files 🦋🌸