diff options
Diffstat (limited to 'vendor/plugins/gettext_i18n_rails/Readme.md')
| -rw-r--r-- | vendor/plugins/gettext_i18n_rails/Readme.md | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/vendor/plugins/gettext_i18n_rails/Readme.md b/vendor/plugins/gettext_i18n_rails/Readme.md new file mode 100644 index 000000000..d3e11845f --- /dev/null +++ b/vendor/plugins/gettext_i18n_rails/Readme.md @@ -0,0 +1,215 @@ +[FastGettext](http://github.com/grosser/fast_gettext) / Rails integration. + +Translate via FastGettext, use any other I18n backend as extension/fallback. + +Rails does: `I18n.t('syntax.with.lots.of.dots')` with nested yml files +We do: `_('Just translate my damn text!')` with simple, flat mo/po/yml files or directly from db +To use I18n calls add a `syntax.with.lots.of.dots` translation. + +[See it working in the example application.](https://github.com/grosser/gettext_i18n_rails_example) + +Setup +===== +### Installation + +#### Rails 3 + +##### As plugin: + + rails plugin install git://github.com/grosser/gettext_i18n_rails.git + + # Gemfile + gem 'fast_gettext', '>=0.4.8' + +##### As gem: + + # Gemfile + gem 'gettext_i18n_rails' + +##### Optional: +If you want to find translations or build .mo files + # Gemfile + gem 'gettext', '>=1.9.3', :require => false, :group => :development + +#### Rails 2 + +##### As plugin: + + script/plugin install git://github.com/grosser/gettext_i18n_rails.git + sudo gem install fast_gettext + + # config/environment.rb + config.gem "fast_gettext", :version => '>=0.4.8' + +##### As gem: + + gem install gettext_i18n_rails + + # config/environment.rb + config.gem 'gettext_i18n_rails' + + #Rakefile + begin + require "gettext_i18n_rails/tasks" + rescue LoadError + puts "gettext_i18n_rails is not installed, you probably should run 'rake gems:install' or 'bundle install'." + end + +##### Optional: +If you want to find translations or build .mo files + # config/environments/development.rb + config.gem "gettext", :version => '>=1.9.3', :lib => false + +### Locales & initialisation +Copy default locales with dates/sentence-connectors/AR-errors you want from e.g. +[rails i18n](http://github.com/svenfuchs/rails-i18n/tree/master/rails/locale/) into 'config/locales' + +To initialize: + + # config/initializers/fast_gettext.rb + FastGettext.add_text_domain 'app', :path => 'locale', :type => :po + FastGettext.default_available_locales = ['en','de'] #all you want to allow + FastGettext.default_text_domain = 'app' + +And in your application: + + # app/controllers/application_controller.rb + class ApplicationController < ... + before_filter :set_gettext_locale + +Translating +=========== +Performance is almost the same for all backends since translations are cached after first use. + +### Option A: .po files + + FastGettext.add_text_domain 'app', :path => 'locale', :type => :po + + - use some _('translations') + - run `rake gettext:find`, to let GetText find all translations used + - (optional) run `rake gettext:store_model_attributes`, to parse the database for columns that can be translated + - if this is your first translation: `cp locale/app.pot locale/de/app.po` for every locale you want to use + - translate messages in 'locale/de/app.po' (leave msgstr blank and msgstr == msgid) + +New translations will be marked "fuzzy", search for this and remove it, so that they will be used. +Obsolete translations are marked with ~#, they usually can be removed since they are no longer needed + +#### Unfound translations with rake gettext:find +Dynamic translations like `_("x"+"u")` cannot be fond. You have 4 options: + + - add `N_('xu')` somewhere else in the code, so the parser sees it + - add `N_('xu')` in a totally separate file like `locale/unfound_translations.rb`, so the parser sees it + - use the [gettext_test_log rails plugin ](http://github.com/grosser/gettext_test_log) to find all translations that where used while testing + - add a Logger to a translation Chain, so every unfound translations is logged ([example]((http://github.com/grosser/fast_gettext))) + +### Option B: Traditional .po/.mo files + + FastGettext.add_text_domain 'app', :path => 'locale' + + - follow Option A + - run `rake gettext:pack` to write binary GetText .mo files + +### Option C: Database +Most scalable method, all translators can work simultaneously and online. + +Easiest to use with the [translation database Rails engine](http://github.com/grosser/translation_db_engine). +Translations can be edited under `/translation_keys` + + FastGettext::TranslationRepository::Db.require_models + FastGettext.add_text_domain 'app', :type => :db, :model => TranslationKey + +I18n +==== + I18n.locale <==> FastGettext.locale.to_sym + I18n.locale = :de <==> FastGettext.locale = 'de' + +Any call to I18n that matches a gettext key will be translated through FastGettext. + +Namespaces +========== +Car|Model means Model in namespace Car. +You do not have to translate this into english "Model", if you use the +namespace-aware translation + s_('Car|Model') == 'Model' #when no translation was found + +XSS / html_safe +=============== +If you trust your translators and all your usages of % on translations:<br/> + # config/environment.rb + GettextI18nRails.translations_are_html_safe = true + +String % vs html_safe is buggy (can be used for XSS on 1.8 and is always non-safe in 1.9)<br/> +My recommended fix is: `require 'gettext_i18n_rails/string_interpolate_fix'` + + - safe stays safe (escape added strings) + - unsafe stays unsafe (do not escape added strings) + +ActiveRecord - error messages +============================= +ActiveRecord error messages are translated through Rails::I18n, but +model names and model attributes are translated through FastGettext. +Therefore a validation error on a BigCar's wheels_size needs `_('big car')` and `_('BigCar|Wheels size')` +to display localized. + +The model/attribute translations can be found through `rake gettext:store_model_attributes`, +(which ignores some commonly untranslated columns like id,type,xxx_count,...). + +Error messages can be translated through FastGettext, if the ':message' is a translation-id or the matching Rails I18n key is translated. + +####Option A: +Define a translation for "I need my rating!" and use it as message. + validates_inclusion_of :rating, :in=>1..5, :message=>N_('I need my rating!') + +####Option B: + validates_inclusion_of :rating, :in=>1..5 +Make a translation for the I18n key: `activerecord.errors.models.rating.attributes.rating.inclusion` + +####Option C: +Add a translation to each config/locales/*.yml files + en: + activerecord: + errors: + models: + rating: + attributes: + rating: + inclusion: " -- please choose!" +The [rails I18n guide](http://guides.rubyonrails.org/i18n.html) can help with Option B and C. + +Plurals +======= +FastGettext supports pluralization + n_('Apple','Apples',3) == 'Apples' + +Abnormal plurals like e.g. Polish that has 4 different can also be addressed, see [FastGettext Readme](http://github.com/grosser/fast_gettext) + +Customizing list of translatable files +====================================== +When you run + + rake gettext:find + +by default the following files are going to be scanned for translations: {app,lib,config,locale}/**/*.{rb,erb,haml}. If +you want to specify a different list, you can redefine files_to_translate in the gettext namespace in a file like +lib/tasks/gettext.rake: + + namespace :gettext do + def files_to_translate + Dir.glob("{app,lib,config,locale}/**/*.{rb,erb,haml,rhtml}") + end + end + +[Contributors](http://github.com/grosser/gettext_i18n_rails/contributors) +====== + - [ruby gettext extractor](http://github.com/retoo/ruby_gettext_extractor/tree/master) from [retoo](http://github.com/retoo) + - [Paul McMahon](http://github.com/pwim) + - [Duncan Mac-Vicar P](http://duncan.mac-vicar.com/blog) + - [Ramihajamalala Hery](http://my.rails-royce.org) + - [J. Pablo Fernández](http://pupeno.com) + - [Anh Hai Trinh](http://blog.onideas.ws) + - [ed0h](http://github.com/ed0h) + - [Nikos Dimitrakopoulos](http://blog.nikosd.com) + +[Michael Grosser](http://grosser.it)<br/> +grosser.michael@gmail.com<br/> +Hereby placed under public domain, do what you want, just do not hold me accountable... |