view release on metacpan or  search on metacpan

lib/Locale/TextDomain/OO.pm  view on Meta::CPAN

sub new {
    my ($class, @args) = @_;

    return Locale::TextDomain::OO::Translator->new(
        Locale::TextDomain::OO::Translator->load_plugins(@args),
    );
}

sub instance {
    my ($class, @args) = @_;

    require Locale::TextDomain::OO::Singleton::Translator;
    my $instance = Locale::TextDomain::OO::Singleton::Translator->_has_instance; ## no critic (PrivateSubs)
    $instance
        and return $instance;

    return Locale::TextDomain::OO::Singleton::Translator->instance(
        Locale::TextDomain::OO::Singleton::Translator->load_plugins(@args),
    );
}

1;

__END__

=head1 NAME

Locale::TextDomain::OO - Perl OO Interface to Uniforum Message Translation

$Id: OO.pm 724 2018-12-24 11:50:32Z steffenw $

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

=head1 VERSION

1.036

Starting with version 1.000 the interface has changed.

=head1 DESCRIPTION

This module provides a high-level interface to Perl message translation.

It is based on Singleton objects for translator and lexicon.
So it is easy to attach that without any Web or Cmd plugins.
There is no conflict between singleton and more than 1 project at the same time.
The lexicon has a project key to split.

You are able to use the translator singleton earlier then language initialization
but do not call the translation methods before.
Create the lexicon singleton during compilation time.

Maketext is implemented here for moving existing projects to Gettext.

BabelFish is implemented for multi-plural in one phrase.
But use BabelFish in that case only.
BabelFish is much harder to translate (similar to maketext)
by translation office or automatic translation.

For combinded plurals watch the Gettext multiplural example.
In that case you have to write that awful long formulas but it is possibel.

Never use keys instead of English language in code.
You can't read, execute (with placeholders) or test your code without translation.

=head2 Why a new module?

This module is similar
to L<Locale::TextDomain|Locale::TextDomain>
and L<Locale::Maketext|Locale::Maketext>.

This module is not using/changing any system locale
like L<Locale::TextDomain|Locale::TextDomain>.

This module has no magic in how to get the language
like L<Locale::Maketext|Locale::Maketext>.
You decide what you need.

There are some plugins, so it is possible
to use different the Gettext, BabelFish and/or Maketext styles.

Locale::TextDomain::OO has a flexible object oriented interface
based on L<Moo|Moo>.

Creating the Lexicon and translating are two split things.
So it is possible to create the lexicon during the compilation phase.
The connection between both is the singleton mechanism
of the lexicon module using L<MooX::Singleton|MooX::Singleton>.

=head2 Plugin for the web framework?

This module was first used in a Catalyst based web project.

It was great to call everything on the Catalyst context object.
It was great until we used module in web and shell scripts together
and called the translation methods there.

What we have done was removing the Catalyst Maketext plugin.
We are using a role in the Catalyst application
and so we can call all the translation methods
on the Catalyst context object like before.

For the shell scripts we have a role for this Cmd's
to call all the methods on C<$self>.

In that roles we delegate a bunch of methods
to Locale::TextDomain::OO.
We also added our project specific methods there.

Write you own role. There is no need for a plugin for any framework.

=head2 Who is sets the languages?

Not this module.

In a web application are lots of ideas to do that.
But never we use the server settings, never.

The HTTP request contains that information.
Extend this with super and panic languages.
Normally you support only a bunch of world languages, so reduce.

lib/Locale/TextDomain/OO.pm  view on Meta::CPAN

Or your application has a language selection menu.
(Never use flags for that.
There are multilanguage countries and more countries have the same language.)

=head2 How to extract the project files?

Use module
L<Locale::TextDomain::OO::Extract|Locale::TextDomain::OO::Extract>.
This is a base class for all source scanner to create po/pot files.
Use this base class and give this module the rules
or use one of the already extended classes.
L<Locale::TextDomain::OO::Extract::Perl|Locale::TextDomain::OO::Extract::Perl>
is a extension for Perl code and so on.

=head2 How to build the lexicon - without Gettext tools?

Use module
L<Locale::TextDomain::OO::Extract::Process|Locale::TextDomain::OO::Extract::Process>.
This is able to read, strip, extract, merge, write and clean PO and MO files.

There is a module named
L<Locale::TextDomain::OO::Util::JoinSplitLexiconKeys|Locale::TextDomain::OO::Util::JoinSplitLexiconKeys>.
That helps you to build the lexicon keys.
Do not join the keys by yourself, it can break in future versions.
Use the category, domain, language and project part to describe your lexicon.
category, domain and language you can use during translation.
The only reason for project is to separate your different lexicons.

=head2 How to use the lexicon?

The lexicons or all lexicons are stored in memory.
The idea to build a combined lexicon is overwriting hash values by same key.
So read and overwrite common stuff with specials.
In an example case the region file en-gb.mo contains only the differences.
The common file en.mo contains all messages.
So it is possible to create full lexicons for any language and region.
What you have to describe is:
Where are the files - directories.
Pick up the common file en.mo as en.
Pick up the common file en.mo and the special en-gb.mo as en-gb.

=head2 Do not follow the dead end of Locale::Maketext!

But it is allowed to use that writing for backward compatiblity.

What is the problem of Maketext?

=over

=item *

Locale::Maketext allows 2 plural forms (and zero) only.
This is changeable,
but the developer has to control the plural forms.
He is not an omniscient translator.

Gettext allows as much as needed plural forms at destination language.

=item *

Maketext has a plural formula as placeholder in strings to translate.
Gettext has fully readable strings with simple placeholders.
Then a very good automatic translation is possible and this module helps you.

(Some projects have keywords instead of English language in code.
This module helps you to write readable, uncrypic code.
Programmers optimisation is a very bad idea for translations.
Never split a sentence.)

=item *

'quant' inside a phrase is the end of the automatic translation
because quant is an 'or'-construct.

    begin of phrase [quant,_1,singular,plural,zero] end of phrase

Gettext used full qualified sentences.

=item *

The plural form is allowed after a number,
followed by a whitespace,
not a non-breaking whitespace.

    1 book
    2 books

A plural form can not be before a number.

    It is 1 book.
    These are 2 books.

Gettext is using full qualified sentences.

=item *

There is no plural form without a number in the phrase.

    I like this book.
    I like these books.

Gettext used an extra count to select the plural form.
Placeholders are placeholders not combined things.

=item *

Placeholders are numbered serially.
It is difficult to translate this
because the sense of the phrase could be lost.

    Still [_1] [_2] to [_3].

    Still 5 hours to midnight.
    Still 15 days to Olympics.

Locale::TextDomain::OO used named placeholders like

    Still {count :num} {datetime unit} to {event}.

=item *