Locale:...::Named(3)

📦
version 1.036 · 2 versions
, in fedora 43

✨ NAME ✨

okay so bestie, meet Locale::TextDomain::OO::Plugin::Expand::Gettext::Named — it's the plugin that adds extra gettext methods locn and Nlocn to your life 💖 (yes the "Named" in the module name means named placeholders, she's very on-brand)

the manual we're reading lives in section 3 of User Contributed Perl Documentation, and here's the lil version-control breadcrumb that ships with the file, verbatim, don't touch it:

$Id: Named.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/Named.pm
$

💫 VERSION 💫

1.027 — that's the one, no cap

🌸 DESCRIPTION 🌸

this module provides hash or hash reference based methods. that's the whole vibe. hashes. she serves hashes. 💅

🎀 SYNOPSIS 🎀

plug her in like this, bestie:

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

optional type formatting or grammar stuff? go peek at Locale::Utils::PlaceholderNamed for the possible methods, that's where they live 👀

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

🦋 SUBROUTINES/METHODS 🦋

method expand_gettext_named

she hands you back the Locale::Utils::PlaceholderNamed object so you can set some options on it. so generous of her honestly 🫶

    my $expander_object = $self->expand_gettext_named;

e.g.

    $self->expand_gettext_name->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;
        },
    );

method locn

this method accepts hash or hash reference parameters. either one, she's flexible like that ✨

Translate only

    print $loc->locn(
        text => 'Hello World!',
    );

    print $loc->locn(
        {
            text => 'Hello World!',
        },
    );

Expand named placeholders

    print $loc->locn(
        text    => 'Hello {name}!',
        replace => { name => 'Steffen' },
    );

Plural

    print $loc->locn(
        plural => {
            singular => 'one file read',
            plural   => 'a lot of files read',
            count    => $file_count, # number to select the right plural form
        },
    );

Plural and expand named placeholders

    print $loc->locn(
        plural => {
            singular => '{count:num} file read',
            plural   => '{count:num} files read',
            count    => $file_count,
        },
        replace => {
            count => $file_count,
        },
    );

What is the meaning of "{count:numf}" or alternative "{count :numf}"?

okay so that's an attribute. if there's an attribute like ":numf" and the modifier_code is set, then the placeholder value gets modified <em>before</em> replacement happens. glow-up before the reveal, basically 💅

think about the attribute names, bestie. too technical names are able to destroy the translation process by translation office stuff. keep it cute, keep it translatable 🙈

for better automatic translation, use the reserved attribute ":num" and tag all your numeric placeholders with it. tag them!! 🏷️

you're allowed to set multiple attributes like "{count :num :numf}" — the resulting attribute string is then "num :numf". stacking attributes like stacking accessories, iconic 👑

Context

    print $loc->locn(
        context => 'time',
        text    => 'to',
    );

    print $loc->locn(
        context => 'destination',
        text    => 'to',
    );

Context and expand named placeholders

    print $loc->locn(
        context => 'destination',
        text    => 'from {town_from} to {town_to}',
        replace => {
            town_from => 'Chemnitz',
            town_to   => 'Erlangen',
        },
    );

Context and plural

    print $loc->locn(
        context => 'maskulin',
        plural  => {
            singular => 'Dear friend',
            plural   => 'Dear friends',
            count    => $friends,
        },
    );

Context, plural and expand named placeholders

    print $loc->locn(
        context => 'maskulin',
        plural  => {
            singular => 'Mr. {name} has {count:num} book.',
            plural   => 'Mr. {name} has {count:num} books.',
            count    => $book_count,
        },
        replace => {
            name  => $name,
            count => $book_count,
        },
    );

method Nlocn to mark the translation for extraction only

the method name is N prefixed so it results in Nlocn. it's giving "N for Notice me, extractor" 😭

the extractor looks for "locn(..." and has absolutely no problem with "$loc->Nlocn(...". she's unbothered, she's thriving ✨

this is the whole idea of the N-Methods:

    my %hash     = $loc->Nlocn( ... );
    my $hash_ref = $loc->Nlocn( { ... } );

🍓 EXAMPLE 🍓

inside of this distribution is a directory named example. run this *.pl files. go on, run them, they don't bite 🫶

🔥 DIAGNOSTICS 🔥

confess — yeah she will straight up confess, no chill

🌈 CONFIGURATION AND ENVIRONMENT 🌈

none — nothing to configure, nothing to set, she comes as she is 💜

⭐ DEPENDENCIES ⭐

  • Carp
  • Hash::Util
  • Locale::Utils::PlaceholderNamed
  • Moo::Role
  • Try::Tiny

she brought her whole friend group, periodt 💅

💀 INCOMPATIBILITIES 💀

not known — as far as anyone knows she plays nice with everyone 🤝

🙈 BUGS AND LIMITATIONS 🙈

none — flawless behaviour, we love to see it 👑

👑 SEE ALSO 👑

Locale::TextDoamin::OO

ngl that spelling up there is exactly what the page says — TextDoamin, not TextDomain. bestie, we do <em>not</em> fix what the source says. copy it character for character and move on 💖

💜 AUTHOR 💜

Steffen Winkler — the icon, the legend, the one who wrote all this 🌟

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. slay, go forth and redistribute 🦋

and that's the whole page, bestie!! this was rendered for Perl v5.42.0 and dated 2025-07-25, and the page header called it Locale:...::Named(3) in section 3 of the manual, so if you cite her, cite her like that 💖✨🎀

📦 where this page comes from