English
资源说明：localist
= LOCALIST PLUGIN v0.5
"If you need to go global, a Localist may help!" :-)
Localist helps in multilanguage/globalized applications. It automatically finds the best match between the locales accepted by your users and the locales supported by your application (per rules defined in RFC2616, section 14.4: HTTP/1.1 - Header Field Definitions - Accept-Language) and maintain it in successive requests. It also offers a nice country-flag menu to allow the users to manually switch to another locale.
== Features:
* only 3-5 lines of code required to use it
* finds, sets and maintains the best locale match in successive requests
* smart fallback when no match is possible
* RFC2616 compilant
* provides a nice flag menu with the active locale indicator
* allows the user to manually switch the locale
* includes the flag icons of all the ISO3166-1 alpha-2 countries
* fully configurable (by variables)
* fully customizable (by overriding methods and templates)
= REQUIREMENTS
Download the meta-tools lib form here http://ruby.4pro.net/meta-tools/download/ and install it:
% [sudo] gem install meta-tool-1.0.gem
= REPOSITORY
http://rails-localist.googlecode.com/svn/trunk/
= QUICK START
in app/controllers/application.rb:
before_filter :localist
in config/environment.rb:
Localist.supported_locales = %w[ en-US it-IT es-ES fr-FR ..... ]
Localist.callback = lambda{ |client_locale| do_something_with( client_locale ) }
in the head container of your layout:
<%= stylesheet_link_tag "localist/stylesheet.css", :media=>'all' %>
somewhere in the body container of your layout or template:
<%= localist_menu %>
= USAGE
Use the :localist method as a before_filter in your controller (usually in app/controllers/application_controller.rb), and eventually the localist_menu helper. You should also add a tag in your layout:
<%= stylesheet_link_tag "localist/stylesheet.css", :media=>'all' %>
== Before Filter
=== before_filter :localist
The :localist filter parses the HTTP_ACCEPT_LANGUAGE of the request and finds the best match with the locales supported by your application. If no best match is found, it consider as the best match the Localist.default_locale (which has a default of Localist.supported_locales.first) unless you have defined a :localist_no_match method. In that case it simply give up and pass the decision about what to do to your method.
== Variables
=== Localist.supported_locales
The list of the locales supported by your application. You must set it!
=== Localist.callback
As soon as Localist finds the best locale match (or retrieve it from the params or the cookies), it sets @localist_active_locale and calls the callback, passing it the best match as the single parameter. The callback can be a Proc or a Symbol (representing a defined method). In the callback you can set the locale of your preferred i18n plugin. If you don't set any callback, you can use the @localist_active_locale in your code however.
=== Localist.symbol
This is the symbol used for the cookie that localist uses to maintain the locale between requests and used for the temporary param when the client manually switches the locale. Default :locale.
=== Localist.auto_setup
When true, localist syncronizes the public flag images with the locales that your application supports. That means that when you restart the server, it remove the old flags dir, and make another one, copying inside it the used flag assets. Default true in development mode and false otherwise.
=== Localist.strict2616
Set this to true for strict RFC2616 compatibility. It is false by default because strictness is useful in very special cases: change it only if you know what you are doing.
== Helpers
=== localist_menu([options])
This is a helper that creates a switch menu, with a .png icon for each country in your Localist.supported_locales. It uses the alpha-2 country code as defined in the ISO3166-1. If you use standard locale names (e.g en-US or it-IT) it finds the correct flag and use it as the link to switch to the localized page. The Flag icons distributed with localist come from http://www.famfamfam.com.
The options of the localist_menu helper may be useful for personalizing the menu or for supporting 2 different locales in the same page. They are all optionals:
[:supported_locales] (default: Localist.supported_locales)
[:active] (default: @localist_active_locale)
[:symbol] (default: Localist.symbol)
[:template] (default: /app/views/localist/menu.rhtml, overridable in /app/view/localist/menu.rhtml or settable as you need)
All the options (less the :template) are available as the localist_menu hash in the template.
=== localist_flag_tag(locale)
This is a helper used in the localist menu template, which returns the image_tag for the flag.
= EXAMPLE
in config/environment.rb:
# mandatory assignation
Localist.supported_locales = %w[ en-US it-IT es-ES fr-FR]
# optional assignations
Localist.callback = lambda{|best_match| Locale.set(best_match)} # or :my_method_for_globalize
Localist.default_locale = "es-ES"
Localist.symbol = :my_symbol
Localist.auto_setup = false
in app/controllers/application_controller.rb:
before_filter :localist
in the head container of your layout:
<%= stylesheet_link_tag "localist/stylesheet", :media=>'all' %>
in any layout or template:
<%= localist_menu %>
Syncronized files (auto-copied if :auto_setup => true):
public/images/localist/flags/us.png
public/images/localist/flags/it.png
public/images/localist/flags/es.png
public/images/localist/flags/fr.png
public/stylesheets/localist/stylesheet.css
= CHANGELOG
== Version 0.5
* First public release
= TO DO
* Adding tests
= AUTHOR AND COPYRIGHT
Copyright (c) 2007 by Domizio Demichelis
This plugin is free software. It may be used, redistributed and/or modified
under the same terms as Rails itself
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
