Locale:...xt::Loc(3)

✨ NAME ✨

okay bestie, welcome to the User Contributed Perl Documentation manual, and buckle up because this one is a bop 💅

Locale::TextDomain::OO::Plugin::Expand::Gettext::Loc — it gives you extra gettext methods, all cute and cozy under the loc_ prefix. That's the whole personality. iconic ✨

Also, because version control said so, here's the literal breadcrumb trail this module left behind:

$Id: Loc.pm 651 2017-05-31 18:10:43Z steffenw $

$HeadURL:
svn+ssh://steffenw@svn.code.sf.net/p/perl-gettext-oo/code/module/trunk/lib/Locale/TextDomain/OO/Plugin/Expand/Gettext/Loc.pm
$

---

🔢 VERSION 🔢

1.027 — say it with me. one point oh two seven. 🎀

---

🌸 DESCRIPTION 🌸

This module hands you an extra gettext method for dealing with static domain and category handling. That's it, that's the job, and it does it well. 💖

---

📜 SYNOPSIS 📜

Set it up as a plugin like so:

    my $loc = Locale::Text::TextDomain::OO->new(
        plugins => [ qw (
            Expand::Gettext::Loc
            ...
        )],
        ...
    );

If you're into optional type formatting or grammar stuff, go peek at Locale::Utils::PlaceholderNamed — that's where the possible methods live. 👀

    $loc->expand_gettext_loc->modifier_code($code_ref);

---

🛠️ SUBROUTINES/METHODS 🛠️

💫 method expand_gettext_loc 💫

This one gives you back the Locale::Utils::PlaceholderNamed object, so you can go in and set whatever options your heart desires.

    my $expander_object = $self->expand_gettext_loc;

e.g.

    $self->expand_gettext_loc->modifier_code(
        sub {
            my ( $value, $attribute ) = @_;
            if ( $attribute eq 'numf' ) {
                # modify that numeric $value
                # e.g. change 1234.56 to 1.234,56 or 1,234.56
                ...
            }
            elsif ( $attribute eq 'accusative' ) {
                # modify the string with that grammar rule
                # e.g. needed for East-European languages
                # write grammar rules only on msgstr/msgstr_plural[n]
                # and not on msgid
                ...
            }
            ...
            return $value;
        },
    );

💫 translation methods 💫

so, how do you even build one of these method names? glad you asked 🫶

Start with loc_ and then append "n", "p" and/or "x" — in alphabetic order, no chaos allowed.

• loc_ — Special marked for extraction.
• n — Using plural forms.
• p — Context is the first parameter.
• x — Last parameters as hash/hash_ref are for named placeholders.

✨ method loc_ ✨

Just translate, nothing extra:

    print $loc->loc_(
        'Hello World!',
    );

✨ method loc_x ✨

Expand those named placeholders:

    print $loc->loc_x(
        'Hello {name}!',
        # hash or hash_ref
        name => 'Steffen',
    );

✨ method loc_n ✨

Plural time 🌈

    print $loc->loc_n(
        'one file read',       # Singular
        'a lot of files read', # Plural
        $file_count,           # number to select the right plural form
    );

✨ method loc_nx ✨

Plural and named placeholder expansion, a duo:

    print $loc->loc_nx(
        '{count:numf} file read',
        '{count:numf} files read',
        $file_count,
        # hash or hash_ref
        count => $file_count,
    );

okay so what does {count:numf} mean? or, alternatively, {count :numf}?

It's an attribute. If an attribute like ":numf" is hanging around and modifier_code is set, then the placeholder value gets modified before it's replaced. 💅

And bestie, think about your attribute names. If they get too technical, they can literally destroy the translation process once the translation office people get their hands on them. 😭

For smoother automatic translation, use the reserved attribute ":num" and tag every single numeric placeholder.

You can stack multiple attributes too, like "{count :num :numf}" — the resulting attribute string in that case is "num :numf".

✨ method loc_p ✨

Context, baybee:

    print $loc->loc_p(
        'time', # Context
        'to',
    );

    print $loc->loc_p(
        'destination', # Context
        'to',
    );

✨ method loc_px ✨

Context plus named placeholder expansion:

    print $loc->loc_px(
        'destination',
        'from {town_from} to {town_to}',
        # hash or hash_ref
        town_from => 'Chemnitz',
        town_to   => 'Erlangen',
    );

✨ method loc_np ✨

Context plus plural:

    print $loc->loc_np(
        'maskulin',
        'Dear friend',
        'Dear friends',
        $friends,
    );

✨ method loc_npx ✨

The full trio — context, plural, and named placeholder expansion:

    print $loc->loc_npx(
        'maskulin',
        'Mr. {name} has {count:num} book.',
        'Mr. {name} has {count:num} books.',
        $book_count,
        # hash or hash_ref
        name  => $name,
        count => $book_count,
    );

💫 Methods to mark the translation for extraction only 💫

Same naming logic, different prefix. How do you build the method name?

Use Nloc_ and append it with "n", "p" and/or "x" in alphabetic order.

• loc_ — Special marked for extraction.
• n — Using plural forms.
• p — Context is the first parameter.
• x — Last parameters as hash/hash_ref are for named placeholders.

✨ methods Nloc_, Nloc_x, Nloc_n, Nloc_nx, Nloc_p, Nloc_px, Nloc_np, Nloc_npx ✨

The extractor goes looking for "loc_('..." and it has absolutely zero problem with "$loc->Nloc_('...". 😌

That right there is the entire idea behind the N-Methods.

    $loc->Nloc_('...');
    $loc->Nloc_x('...', ...);
    ...

---

🍓 EXAMPLE 🍓

Inside this distribution there's a directory named example. Go run those *.pl files, fr fr.

---

🩺 DIAGNOSTICS 🩺

confess

---

⚙️ CONFIGURATION AND ENVIRONMENT ⚙️

none

---

📦 DEPENDENCIES 📦

• Locale::Utils::PlaceholderNamed
• Moo::Role

---

💀 INCOMPATIBILITIES 💀

not known

---

🙈 BUGS AND LIMITATIONS 🙈

none

---

👀 SEE ALSO 👀

Locale::TextDoamin::OO

---

👑 AUTHOR 👑

Steffen Winkler

---

⭐ LICENSE AND COPYRIGHT ⭐

Copyright (c) 2009 - 2017, Steffen Winkler "<steffenw at cpan.org>". All rights reserved.

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

---

and that's the whole page, bestie 🫶 brought to you by perl v5.42.0, dated 2025-07-25. mwah 💋 go translate something.