NAME
    Locale::Babelfish - Perl I18n using https://github.com/nodeca/babelfish
    format.

VERSION
    version 1.000001

SYNOPSIS
        package Foo;

        use Locale::Babelfish;

        my $bf = Locale::Babelfish->new( { dirs => [ '/path/to/dictionaries' ] } );
        print $bf->t('dictionary.firstkey.nextkey', { foo => 'bar' } );

    More sophisticated example:

        package Foo::Bar;

        use Locale::Babelfish;

        my $bf = Locale::Babelfish->new( {
            # configuration
            dirs         => [ '/path/to/dictionaries' ],
            default_locale => [ 'ru_RU' ], # By default en_US
        } );

        # using default locale
        print $bf->t( 'dictionary.akey' );
        print $bf->t( 'dictionary.firstkey.nextkey', { foo => 'bar' } );

        # using specified locale
        print $bf->t( 'dictionary.firstkey.nextkey', { foo => 'bar' }, 'by_BY' );

        # using scalar as count or value variable
        print $bf->t( 'dictionary.firstkey.nextkey', 90 );
        # same as
        print $bf->t( 'dictionary.firstkey.nextkey', { count => 90, value => 90 } );

        # set locale
        $bf->locale( 'en_US' );
        print $bf->t( 'dictionary.firstkey.nextkey', { foo => 'bar' } );

        # Get current locale
        print $bf->locale;

DESCRIPTION
    Internationalisation with easy syntax

    Created for using same dictionaries on Perl and JavaScript.

METHODS
  new
    Constructor

        my $bf = Locale::Babelfish->new( {
            dirs           => [ '/path/to/dictionaries' ], # is required
            suffix         => 'yaml', # dictionaries extension
            default_locale => 'ru_RU', # by default en_US
        } );

  locale
    Gets or sets current locale.

        $self->locale;
        $self->locale( 'en_GB' );

  prepare_to_compile
        $self->prepare_to_compile()

    Marks dictionary values as refscalars, is they need compilation. Or
    simply compiles them.

  detect_locale
        $self->detect_locale( $locale );

    Detects locale by specified locale/language.

    Returns default locale unless detected.

  load_dictionaries
    Loads dictionaries recursively on specified path.

        $self->load_dictionaries;
        $self->load_dictionaries( \&filter( $file_path ) );

  phrase_need_compilation
        $self->phrase_need_compilation( $phrase, $key )
        $class->phrase_need_compilation( $phrase, $key )

    Is phrase need parsing and compilation.

  on_watcher_change
        $self->on_watcher_change()

    Reloads all dictionaries.

  check_for_changes
        $self->check_for_changes()

    Checks that all files unchanged or calls "on_watcher_change".

    Works when watch option set only.

  t_or_undef
    Get internationalized value for key from dictionary.

        $self->t_or_undef( 'main.key.subkey' );
        $self->t_or_undef( 'main.key.subkey' , { param1 => 1 , param2 => { next_level  => 'test' } } );
        $self->t_or_undef( 'main.key.subkey' , { param1 => 1 }, $specific_locale );
        $self->t_or_undef( 'main.key.subkey' , 1 );

    Where "main" - is dictionary, "key.subkey" - key at dictionary.

  t
    Get internationalized value for key from dictionary.

        $self->t( 'main.key.subkey' );
        $self->t( 'main.key.subkey' , { param1 => 1 , param2 => { next_level  => 'test' } } );
        $self->t( 'main.key.subkey' , { param1 => 1 }, $specific_locale );
        $self->t( 'main.key.subkey' , 1 );

    Where "main" - is dictionary, "key.subkey" - key at dictionary.

    Returns square bracketed key when value not found.

  has_any_value
    Check exist or not key in dictionary.

        $self->has_any_value( 'main.key.subkey' );

    Where "main" - is dictionary, "key.subkey" - key at dictionary.

  set_fallback
        $self->set_fallback( 'by_BY', 'ru_RU', 'en_US');
        $self->set_fallback( 'by_BY', [ 'ru_RU', 'en_US' ] );

    Set fallbacks for given locale.

    When `locale` has no translation for the phrase, fallbacks[0] will be
    tried, if translation still not found, then fallbacks[1] will be tried
    and so on. If none of fallbacks have translation, default locale will be
    tried as last resort.

DICTIONARIES
  Phrases Syntax
    #{varname} Echoes value of variable
    ((Singular|Plural1|Plural2)):variable Plural form
    ((Singular|Plural1|Plural2)) Short plural form for "count" variable

    Example:

        I have #{nails_count} ((nail|nails)):nails_count

    or short form

        I have #{count} ((nail|nails))

    or with zero and onу plural forms:

        I have ((=0 no nails|=1 a nail|#{nails_count} nail|#{nails_count} nails)):nails_count

  Dictionary file example
    Module support only YAML format. Create dictionary file like:
    dictionary.en_US.yaml where "dictionary" is name of dictionary and
    "en_US" - its locale.

        profile:
            apps:
                forums:
                    new_topic: New topic
                    last_post:
                        title : Last message
        demo:
            apples: I have #{count} ((apple|apples))

  Encoding
    UTF-8 (Perl internal encoding).

  DETAILS
    Dictionaries loaded at instance construction stage.

    All scalar values will be saved as scalar refs if needs compilation (has
    Babelfish control sequences).

    t_or_undef method translates specified key value.

    Result will be compiled when scalarref. Result of compilation is scalar
    or coderef.

    Result will be executed when coderef.

    Scalar/hashref/arrayref will be returned as is.

    Watch option supported.

SEE ALSO
    <https://github.com/nodeca/babelfish>

AUTHORS
    *   Akzhan Abdulin <akzhan@cpan.org>

    *   Igor Mironov <grif@cpan.org>

    *   REG.RU LLC

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2014 by Akzhan Abdulin.

    This is free software, licensed under:

      The MIT (X11) License

