Repository files navigation

Locale::Wolowitz - Dead simple localization with JSON.

    # in ./i18n/locales.coll.json    {            "Welcome!": {                    "he": "ברוכים הבאים!",                    "es": "Bienvenido!"            },            "I'm using %1": {                    "he": "אני משתמש ב%1",                    "es": "Estoy usando %1"            },            "Linux": {                    "he": "לינוקס"            }    }    # in your app    use Locale::Wolowitz;    my $w = Locale::Wolowitz->new( './i18n' );    print $w->loc('Welcome!', 'es'); # prints 'Bienvenido!'    print $w->loc("I'm using %1", 'he', $w->loc('Linux', 'he')); # prints "אני משתמש בלינוקס"    # you can also directly load data (useful if data is not in files, but say in database)    $w->load_structure({            hello => {                    he => 'שלום',                    fr => 'bonjour'            }    });    print $w->loc('hello', 'he'); # prints "שלום"

Locale::Wolowitz is a very simple text localization system. Yes, anotherlocalization system.

Frankly, I never realized how to use the standard Perl localization systemssuch asLocale::Maketext,Gettext,Data::Localize or whatever.It seems they are more meant to localize an application to the languageof the system on which its running, which isn't really what I need. Most of thetime, seeing as how I'm mostly writing web applications, I wish to localizemy applications/websites according to the user's wishes, not by the system.For example, I may create a content management system where the user canselect the interface's language. Also, I grew to hate the standard .pofiles, and thought using a JSON format might be more comfortable.

Locale::Wolowitz allows you to provide different languages to end-users of yourapplications. To some extent, when writing RESTful web applications, this meansyou can perform language negotiation with visitors (seeContent negotiation on Wikipedia).

Locale::Wolowitz works with JSON files. Each file can serve one or more languages.When creating an instance of this module, you are required to pass a pathto a directory where your application's JSON localization files are present.These are all loaded and merged into one big hash-ref (unless you tell the moduleto only load a specific file), which is stored in memory. A file with only onelanguage has to be named .json (where is the name of the language,you'd probably want to use the two-letter ISO 639-1 code). A file with multiplelanguages must end with .coll.json (this requirement will probably be lifted inthe future).

The basic idea is to write your application in a base language, and usethe JSON files to translate text to other languages. For example, lets sayyou're writing your application in English and translating it to Hebrew,Spanish, and Dutch. You put Spanish and Dutch translations in one file,and since everybody hates Israel, you put Hebrew translations alone.The Spanish and Dutch file can look like this:

    # es_and_nl.coll.json    {            "Welcome!": {                    "es": "Bienvenido!",                    "nl": "Welkom!"            },            "I'm using %1": {                    "es": "Estoy usando %1",                    "nl": "Ik gebruik %1"            },            "Linux": {} // this line can also be missing entirely    }

While the Hebrew file can look like this:

    # he.json    {            "Welcome!": "ברוכים הבאים!",            "I'm using %1": "אני משתמש ב%1",            "Linux": "לינוקס"    }

When loading these files, Locale::Wolowitz internally merges the two files intoone structure:

    {            "Welcome!" => {                    "es" => "Bienvenido!",                    "nl" => "Welkom!",                    "he" => "ברוכים הבאים!",            },            "I'm using %1" => {                    "es" => "Estoy usando %1",                    "nl" => "Ik gebruik %1",                    "he" => "אני משתמש ב%1",            },            "Linux" => {                    "he" => "לינוקס",            }    }

Notice the "%1" substrings above. This is a placeholder, just like in otherlocalization paradigms - they are replaced with content you provide, usuallydynamic content. In Locale::Wolowitz, placeholders are written with a percentsign, followed by an integer, starting from 1 (e.g. %1, %2, %3). When passingdata for the placeholders, make sure you're passing scalars, or printableobjects, otherwise you'll encounter errors.

We can also see here that Spanish and Dutch have no translation for "Linux".Since Linux is written "Linux" in these languages, they have no translation.When attempting to translate a string that has no translation to the requestedlanguage, or has no reference in the JSON files at all, the string issimply returned as is (but placeholders will still be replaced as expected).

Say you write your application in English (and thus 'en' is your baselanguage). Since Locale::Wolowitz doesn't really know what your base language is,you can translate texts within the same language. This is more useful whenyou want to give some of your strings an identifier. For example:

    "copyrights": {            "en": "Copyrights, 2010 Ido Perlmuter",            "he": "כל הזכויות שמורות, 2010 עידו פרלמוטר"    }

Creates a new instance of this module. A path to a directory inwhich JSON localization files exist, or a path to a specific localizationfile,may be supplied. If you pass a directory, all JSON localization filesin it will be loaded and merged as described above. If you pass one file,only that file will be loaded.

Note thatLocale::Wolowitz will ignore dotfiles in the provided path (e.g.hidden files, backups files, etc.).

A hash-ref of options can also be provided. The only option currently supportedisutf8, which is on by default. If on, all JSON files are assumed to be inUTF-8 character set and will be automatically decoded. Provide a false valueif your files are not UTF-8 encoded, for example:

    Locale::Wolowitz->new( '/path/to/files', { utf8 => 0 } );

Receives a path to a directory in which JSON localization files exist, or apath to a specific localization file, and loads (and merges) the localizationdata from the file(s). If localization data was already loaded previously,the structure will be merged, with the new data taking precedence.

You can call this method andload_structure()as much as you want, the data from each call will be merged with existing data.

Receives a hash-ref of localization data similar to that in the JSON filesand loads it into the object (possibly merging with existing data, if any).If$lang is supplied, a one-to-one structure will be assumed, like so:

    load_structure(            { "hello" => "שלום", "world" => "עולם" },            'he'    )

Or, if$lang is not provided, the structure must be the multiple languagestructure, like so:

    load_structure({            "hello" => {                    "he" => "שלום",                    "fr" => "bonjour"            },            "world" => {                    "he" => "עולם",                    "fr" => "monde",                    "it" => "mondo"            }    })

You can call this method andload_path()as much as you want, the data from each call will be merged with existing data.

Returns the string$msg, translated to the requested language (if sucha translation exists, otherwise no traslation occurs). Any other parameterspassed to the method (@args) are injected to the placeholders in the string(if present).

If an argument is an array ref, it'll be replaced witha recursive call toloc with its elements, with the$langargument automatically added. In otherwords, the following two statements are equivalent:

print $w->loc("I'm using %1", 'he', $w->loc('Linux', 'he'));# same result asprint $w->loc("I'm using %1", 'he', [ 'Linux' ]);

Returns a function ref that is likeloc, but with the$lang curried away.

use Locale::Wolowitz;my $w = Locale::Wolowitz->new( './i18n' );my $french_loc  = $w->loc_for('fr');my $german_loc  = $w->loc_for('de');print $french_loc->('Welcome!'); # equivalent to $w->loc( 'Welcome!', 'fr' )

The following exceptions are thrown by this module:

• "You must provide a path to localization directory."

  This exception is thrown if you haven't provided thenew() subroutinea path to a localization file, or a directory of localization files. Readthe documentation for thenew() subroutine above.

• "Can't open localization directory: %s" and "Can't close localization directory: %s"

  This exception is thrown if Locale::Wolowitz failed to open/close the directoryof the localization files. This will probably happen due to permissionproblems. The error message should include the actual reason for the failure.

• "Path must be to a directory or a JSON file."

  This exception is thrown if you passed a wrong value to thenew() subroutineas the path to the localization directory/file. Either the path is wrong and thusdoes not exist, or the path does exist, but is not a directory and not a file.

• "Can't open localization file %s: %s" and "Can't close localization file %s: %s"

  This exception is thrown if Locale::Wolowitz fails to open/close a specific localizationfile. This will usually happen because of permission problems. The error messagewill include both the name of the file, and the actual reason for the failure.

Locale::Wolowitz requires no configuration files or environment variables.

Locale::Wolowitzdepends on the following CPAN modules:

• Carp
• JSON::MaybeXS

Locale::Wolowitz recommendsCpanel::JSON::XS orJSON::XS for fasterparsing of JSON files.

None reported.

No bugs have been reported.

Please report any bugs or feature requests tobug-Locale-Wolowitz@rt.cpan.org, or through the web interface athttp://rt.cpan.org/NoAuth/ReportBug.html?Queue=Locale-Wolowitz.

Ido Perlmuterido@ido50.net

Copyright 2017 Ido Perlmuter

Licensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.