NAME
    Gettext - A GNU Gettext JavaScript implementation

SYNOPSIS
        let po = new Gettext({
            domain: "com.example.api",
            # Get the lang attribute value from <html>
            # Can also use document.getElementsByTagName('html')[0].getAttribute('lang')
            # or in jQuery: $(':root').attr('lang')
            locale: document.documentElement.lang,
            # Under which uri can be found the localised data arborescence?
            # Alternatively, you can set a <link rel="gettext" href="/locale" />
            # or even one specific by language:
            # <link rel="gettext" lang="ja_JP" href="/locale/ja" />
            path: "/locale",
            debug: true
        });

VERSION
        v0.1.0

DESCRIPTION
    This is a standalone JavaScript library using class model to enable the
    reading of json-based po files as well as ".mo" files. Even though it
    can read ".mo" files, it is better to convert the original ".po" files
    to json using the "po.pl" utility that comes in this Text::PO
    distribution. For example:

        ./po.pl --as-json --output /home/joe/www/locale/ja_JP/com.example.api.json ./ja_JP.po

    The class model does not use ES6, but rather one smart invention by John
    Resig (creator of jQuery), making it usable even on older browser
    versions.

    Because on the service side, in Unix environments, the locale value uses
    underscore, such as "ja_JP" while the web-side uses locale with a dash
    such as "ja-JP", to harmonise and given we are dealing with po files, we
    use internally the underscore version, converting it, if necessary.

    See the section "TESTING" below for testing.

CONSTRUCTOR
  new
    Takes the following options and returns a Gettext object.

    *domain*
        The portable object domain, such as "com.example.api"

    *locale*
        The locale, such as "ja_JP", or "en", or it could even contain a
        dash instead of an underscore, such as "en-GB". Internally, though,
        this will be converted to underscore.

    *path*
        The uri path where the gettext localised data are.

        This is used to form a path along with the locale string. For
        example, with a locale of "ja_JP" and a domain of "com/example.api",
        if the path were "/locale", the data po json data would be fetched
        from "/locale/ja_JP/com.example.api.json"

        You will note that the path does not include "LC_MESSAGES" since
        under the web context, it makes no sense at all. See the GNU
        documentation
        <https://www.gnu.org/software/libc/manual/html_node/Using-gettextize
        d-software.html> for more information on this.

CORE METHODS
  gettext
    Provided with a "msgid" represented by a string, and this return a
    localised version of the string, if any is found and is translated,
    otherwise returns the "msgid" that was provided.

        po.gettext( "Hello" );
        # With locale of fr_FR, this would return "Bonjour"

    Note that you can also call it with the special function "_", such as:

        _("Hello");

    See the global function "_" for more information.

  dgettext
    Takes a domain and a message id and returns the equivalent localised
    string if any, otherwise the original message id.

        po.dgettext( 'com.example.auth', 'Please enter your e-mail address' );
        # Assuming the locale currently set is ja_JP, this would return:
        # 電子メールアドレスをご入力下さい。

  ngettext
    Takes an original string (a.k.a message id), the plural version of that
    string, and an integer representing the applicable count. For example:

        po.ngettext( '%d comment awaiting moderation', '%d comments awaiting moderation', 12 );
        # Assuming the locale is ru_RU, this would return:
        # %d комментариев ожидают проверки

  dngettext
    Same as "ngettext", but takes also a domain as first argument. For
    example:

        po.ngettext( 'com.example.auth', '%d comment awaiting moderation', '%d comments awaiting moderation', 12 );
        # Assuming the locale is ru_RU, this would return:
        # %d комментариев ожидают проверки

EXTENDED METHODS
  addItem
    This takes a <locale>, a message id and its localised version and it
    will add this to the current dictionary for the current domain.

  charset
    Returns a string containing the value of the charset encoding as defined
    in the "Content-Type" header.

        p.charset()

  contentEncoding
    Returns a string containing the value of the header "Content-Encoding".

        p.contentEncoding();

  contentType
    Returns a string containing the value of the header "Content-Type".

        p.contentType(); # text/plaiin; charset=utf-8

  currentLang
    Return the current globally used locale. This is the value found in

        <html lang="fr-FR">

    and thus, this is different from the "locale" set in the Gettext class
    object using </setLocale> or upon class object instantiation.

  exists
    Provided with a locale, and this returns true if the locale exists in
    the current domain, or false otherwise.

  fetchLocale
    Given an original string (msgid), this returns an array of <span> html
    element each for one language and its related localised content. For
    example:

        var array = p.fetchLocale( "Hello!" );
        // Returns:
        <span lang="de-DE">Grüß Gott!</span>
        <span lang="fr-FR">Salut !</span>
        <span lang="ja-JP">今日は！</span>
        <span lang="ko-KR">안녕하세요!</span>

  getData
    Takes an hash of options and perform an HTTP query and return a promise.
    The accepted options are:

    *headers*
        An hash of field-value pairs to be used in the request header.

    *method*
        The HTTP method to be used, such as "GET" or "POST"

    *params*
        An hash of key-value pairs to be set and encoded in the http request
        query.

    *responseType*
        The content-type expected in response. This is used to set it to
        "arraybuffer" to load ".mo" (machine object) files.

    *url*
        The url to make the query to.

  getDataPath
    This takes no argument and will check among the "link" html tags for one
    with an attribute "rel" with value "gettext" and no "lang" attribute. If
    found, it will use this in lieu of the *path* option used during object
    instantiation.

    It returns the value found. This is just a helper method and does not
    affect the value of the *path* property set during object instantiation.

  getDomainHash
    This takes an optional hash of parameters and return the global hash
    dictionary used by this class to store the localised data.

        // Will use the default domain as set in po.domain
        var data = po.getDomainHash();
        // Explicitly specify another domain
        var data = po.getDomainHash({ domain: net.example.api });
        // Specify a domain and a locale
        var l10n = po.getDomainHash({ domain: com.example.api, locale: "ja_JP" });

    Possible options are:

    *domain* The domain for the data, such as "com.example.api"
    *locale* The locale to return the associated dictionary.

  getLangDataPath
    This takes a locale as its unique parameter.

    Similar to </getDataPath>, this will search among the "link" html tags
    for those with the attribute "rel" with value "gettext" and an existing
    "lang" attribute. If found it returns the value of the "href" attribute.

    This is used internally during object instantiation when the *path*
    parameter is not provided.

  getLanguageDict
    Provided with a locale, such as "ja_JP" and this will return the
    dictionary for the current domain and the given locale.

  getLocale
    Returns the locale set for the current object, such as "fr-FR" or
    "ja-JP"

    Locale returned are always formatted for the web, which means having an
    hyphen rather than an underscore like in Unix environment.

  getLocales
    Provided with a locale and this will call "fetchLocale" and return those
    "span" tags as a string, joined by a new line

  getLocalesf
    This is similar to "getLocale", except that it does a sprintf internally
    before returning the resulting value.

  getMoData
    Provided with an uri and this will make an http query to fetch the
    remove ".mp" (machine object) file.

    It calls "getData" and returns a promise.

  getPlural
    Returns the array representing the plural rule for the current domain.

    The array returned is composed of 2 elements:

    1. An integer representing the number of possible plural forms
    2. A string representing an expression using "n" as the count provided.
    This string is to be evaluated and will return an offset value used to
    get the right localised plural content in an array of "msgstr"
        The value returned cannot exceed the integer.

  getText
    Provided with an original string, and this will return its localised
    equivalent if it exists, or by default, it will return the original
    string.

  getTextf
    Provided with an original string, and this will get its localised
    equivalent that wil be used as a template for the sprintf function. The
    resulting formatted localised content will be returned.

  getTextDomain
    Returns a string representing the domain currently set, such as
    "com.example.api"

  getXhrObject
    Return an XMLHttpRequest object compliant with older versions of
    Microsoft browsers.

  isSupportedLanguage
    Provided with a locale and this returns true if the language is
    supported or false otherwise.

    This basically look at the current dictionaries loaded so far for
    various languages and check if the locale specified in argument is among
    them.

  language
    Returns a string containing the value of the header "Language".

        p.language();

  languageTeam
    Returns a string containing the value of the header "Language-Team".

        p.languageTeam();

  lastTranslator
    Returns a string containing the value of the header "Last-Translator".

        p.lastTranslator();

  loadDomainData
    Provided with an hash of options and this will get the data, parse it,
    save it.

    This is called by "setTextDomain" and "setLocale"

  mimeVersion
    Returns a string containing the value of the header "MIME-Version".

        p.mimeVersion();

  pluralForms
    Returns a string containing the value of the header "Plural-Forms".

        p.pluralForms();

  poRevisionDate
    Returns a string containing the value of the header "PO-Revision-Date".

        p.poRevisionDate();

  potCreationDate
    Returns a string containing the value of the header "POT-Creation-Date".

        p.potCreationDate();

  projectIdVersion
    Returns a string containing the value of the header
    "Project-Id-Version".

        p.projectIdVersion();

  reportBugsTo
    Returns a string containing the value of the header
    "Report-Msgid-Bugs-To".

        p.reportBugsTo();

  setLocale
    Sets a new locale to be used looking forward.

        po.setLocale( 'fr_FR' ); # po.setLocale( 'fr-FR' ); would also work

  setTextDomain
    Sets a new domain to be used looking forward. Setting a new domain, will
    trigger the Gettext class to fetch its data by executing an http "GET"
    query using "getData" unless the domain is already registered and
    loaded.

        po.setTextDomain( 'com.example.auth' );

GLOBAL FUNCTION
  _
    The special function "_" is standard for gettext. This is a wrapper to
    the following:

    Assuming the global variable TEXTDOMAIN is set, or else that there is a
    script tag:

        <script id="gettext" type="application/json">
        {
            domain: "com.example.api",
            debug: true,
            defaultLocale: "en_US"
        }
        </script>

    If no locale is defined in the json, then it will check for the
    attribute "lang" of the "html" tag, such as:

        <html lang="fr-FR">

    And will instantiate a "Gettext" object, passing it the *domain*,
    *debug* and *locale* parameters as options, and will return the value
    returned by "po.gettext"

    If an improper "msgid" (undefined or null or empty) is provided or there
    is no "domain" to be found, an error will be raised.

CLASS MOParser
  new
    Takes an optional hash of options. Currently supported option is
    *debug*.

    Instantiate a new MOParser object and returns it.

  parse
    This takes a buffer and an hash of options and returns an hash
    representing the msgid-msgstr.

    Acceptable options are:

    *encoding*
        Character encoding used to decode data

  _getEndianness
    Returns the file endianness used. True if it is little endian or false
    if it is big endian.

  _parseHeader
    Read the binary data and returns an hash of field-value pairs
    representing the ".mo" (machine object) file headers.

  _readTranslationPair
    Read the binary data and returns an hash with properties "id" and "str"
    corresponding to the next "msgid" and "msgstr" found.

  _splitPlurals
    Takes a msgid string and a msgstr string and split them to get an array
    of single and plural representations.

    It returns an hash with properties "id" representing the "msgid" and
    "str" containing an array of "msgstr"

TESTING
    On the command line, go to the top directory of the Text::PO
    distribution and launch a small web server using python or anything else
    you would like:

    For Perl:

        # With HTTP::Daemon
        perl -MHTTP::Daemon -e '$d = HTTP::Daemon->new(LocalPort => 8000) or  +die $!; while 
    ($c = $d->accept) { while ($r = $c->get_request) { +$c->send_file_response(".".$r->url->path) } }'

        # After installing the module HTTP::Server::Brick
        perl -MHTTP::Server::Brick -e '$s=HTTP::Server::Brick->new(port=>8000); $s->mount("/"=>{path=>"."}); $s->start'

        # If you have Plack::App::Directory
        perl -MPlack::App::Directory -e 'Plack::App::Directory->new(root=>".");' -p 8000

        # With IO::All
        perl -MIO::All -e 'io(":8000")->fork->accept->(sub { $_[0] < io(-x $1 +? "./$1 |" : $1) if /^GET \/(.*) / })'

    For python 2:

        python -m SimpleHTTPServer

    For python 3:

        python3 -m http.server

    Or using ruby:

        ruby -run -e httpd -p 8000 .

    Or with php:

        php -S localhost:8000

    Or possibly with nodejs if you have it installed:

        # to install http-server
        npm install -g http-server
        # or using brew:
        brew install http-server
        # then
        http-server -c-1 -p 8000

    More information here <https://www.npmjs.com/package/http-server>

    Then, you can go to <http://localhost:8000/share/test.html>

    If all goes well, you will see the result of all the test performed, and
    they should all be marked ok

AUTHOR
    Jacques Deguest <jack@deguest.jp>

SEE ALSO
    Text::PO::Element, Text::PO::MO

    <https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html>,

    <https://en.wikipedia.org/wiki/Gettext>

COPYRIGHT & LICENSE
    Copyright (c) 2020-2021 DEGUEST Pte. Ltd.

    You can use, copy, modify and redistribute this package and associated
    files under the same terms as Perl itself.

