NAME Locale::Wolowitz - Dead simple localization for web apps with JSON. VERSION version 0.2 SYNOPSIS # 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 "אני משתמש בלינוקס" DESCRIPTION Locale::Wolowitz is a very simple text localization system, meant to be used by web applications (but can pretty much be used anywhere). Yes, another localization system. Frankly, I never realized how to use the standard Perl localization systems such as Locale::Maketext, Gettext, Data::Localize or whatever. It seems they are more meant to localize an application to the language of the system on which its running, which isn't really what I need. I want to allow users of my web applications (to put it simply, visitors of a website backed by one of my web apps) to view my app/website in the language of their choice. Also, I grew to hate the standard .po files, and thought using a JSON format might be more comfortable. And so Wolowitz was born. Locale::Wolowitz allows you to provide different languages to end-users of your applications. To some extent, this means you can perform language negotiation with visitors (see Content 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 path to a directory where your application's JSON localization files are present. These are all loaded and merged into one big hash-ref, which is stored in memory. A file with only one language 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 multiple languages must end with .coll.json (this requirement will probably be lifted in the future). The basic idea is to write your application in a base language, and use the JSON files to translate text to other languages. For example, lets say you'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": {} } 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 into one structure: { "Welcome!" => { "es" => "Bienvenido!", "nl" => "Welkom!", "he" => "ברוכים הבאים!", }, "I'm using %1" => { "es" => "Estoy usando %1", "nl" => "Ik gebruik %1", "he" => "אני משתמש ב%1", }, "Linux" => { "he" => "לינוקס", } } We can 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 requested language, or has no reference in the JSON files at all, the string is simply returned as is. Say you write your application in English (and thus 'en' is your base language). Since Locale::Wolowitz doesn't really know what your base language is, you can translate texts within the same language. This is more useful when you want to give some of your strings an identifier. For example: "copyrights": { "en": "Copyrights, 2010 Ido Perlmuter", "he": "כל הזכויות שמורות, 2010 עידו פרלמוטר" } As you've probably already noticed, Wolowitz supports placeholders. In Locale::Wolowitz, placeholders are written with a percent sign, followed by an integer, starting from 1 (e.g. %1, %2, %3). These are replaced by whatever you're passing to the "loc()" method (but make sure you're passing scalars, or printable objects, otherwise you'll encounter errors). CLASS METHODS new( $path ) Creates a new instance of this module. Requires a path to a directory in which JSON localization files exist. They will be automatically loaded. OBJECT METHODS loc( $msg, $lang, [@args] ) Returns the string $msg, translated to the requested language (if such a translation exists, otherwise no traslation occurs). Any other parameters passed to the method (@args) are injected to the placeholders in the string (if present). INTERNAL METHODS _load_locales( $path ) Loads all locale JSON files in the directory $path and returns them as a hash-ref. AUTHOR Ido Perlmuter, "" BUGS Please report any bugs or feature requests to "bug-locale-wolowitz at rt.cpan.org", or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. SUPPORT You can find documentation for this module with the perldoc command. perldoc Locale::Wolowitz You can also look for information at: * RT: CPAN's request tracker * AnnoCPAN: Annotated CPAN documentation * CPAN Ratings * Search CPAN LICENSE AND COPYRIGHT Copyright 2010 Ido Perlmuter. This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See http://dev.perl.org/licenses/ for more information.