README.textile in rich_i18n-1.0.3 vs README.textile in rich_i18n-1.2.0
- old
+ new
@@ -7,14 +7,15 @@
Rich-i18n is a module of E9s ("http://github.com/archan937/e9s":http://github.com/archan937/e9s) which enriches I18n, Formtastic, the String and Symbol classes. This simplifies internationalization of your Rails application making a Rails developers life much easier. A list of features:
h3. I18n
+* @Translate on-site@ - Just specify you want to use Rich-CMS ("http://github.com/archan937/rich_cms":http://github.com/archan937/rich_cms) and you are set to translate in the front-end
* @Default values@ - Use the translation key (or a portion) as default value: @"continue".t@ returns @"continue"@ and @"text.Welcome_to_our_site".t@ returns @"Welcome to our site"@
* @An easy interface@ - Just call the @t@ method on string or symbols to translate
* @Combine translations@ - Joining keys with spaces combines translations: @"Male / Female".t@ returns @"Man / Vrouw"@ in Dutch
-* @Preserve i18n meta data@ - Rich-i18n preserves the key, the actual used I18n key and the actual translation which you can enquire (this can come in handy when implementing a CMS)
+* @Preserve i18n meta data@ - Rich-i18n preserves the translation @key@, @value@, @locale@ and @derivative key@ (the argument passed for translation). Enquiring this can come in handy when implementing an internationalization CMS (see "Rich-CMS":http://github.com/archan937/rich_cms).
h3. Formtastic
* @Labels, seatholders and default values@ - Not only translate labels, but also hint text (so called @seatholders@) and even translate default values
* @Unobtrusive implementation@ - Translate labels and seatholders unobtrusively, in other words: leave your @semantic_form_for@ (view) code completely untouched
@@ -78,25 +79,21 @@
*Note*: please visit "http://github.com/archan937/seat_holder":http://github.com/archan937/seat_holder for more information about SeatHolder.
h3. Testing Rich-i18n out-of-the-box
-Set the default locale to @:nl@ in @environment.rb@:
-
-<pre>
- config.i18n.default_locale = :nl
-</pre>
-
Run the Rails console:
<pre>
./script/console
</pre>
Start translating in Dutch:
<pre>
+ >> I18n.locale = :nl
+ => :nl
>> "Male / Female".t
=> "Man / Vrouw"
</pre>
h2. Usage
@@ -135,32 +132,32 @@
You can combine translations by using passed string containing translation keys joined with spaces.
h3. Translation meta data with EnrichedString
-When translating text, you possibly want to know the @used key@, the @actual used I18n key@ and its @actual translation@. Rich-i18n preserves just that in an @EnrichedString@ which is a subclass of @String@. Calling @.meta_data@ returns a hash with the meta data:
+When translating text, you possibly want to know the @key@, the @value@, the @locale@ and the @derivative key@ (the argument passed for translation). Rich-i18n preserves just that in an @EnrichedString@ which is a subclass of @String@. Calling @.meta_data@ returns a hash with the meta data:
<pre>
>> "MORE".t.class
=> Rich::I18n::Core::EnrichedString
>> "MORE".t.meta_data
- => {:actual_key=>"word.more", :key=>"MORE", :actual_value=>"MEER"}
+ => {:locale=>:nl, :value=>"meer", :derivative_key=>"MORE", :key=>"word.more"}
</pre>
Keep in mind that combined translations are possible and fortunately EnrichedString is able to cope with that. A concatenated translation has @merged_strings@ which contains every segments:
<pre>
>> "More users".t
=> "Meer gebruikers"
>> "More users".t.merged_strings
- => ["Meer", "gebruikers"]
+ => ["Meer", " ", "gebruikers"]
>> "More users".t.meta_data
=> nil
>> "More users".t.merged_strings.first.meta_data
- => {:actual_key=>"word.more", :key=>"More", :actual_value=>"Meer"}
+ => {:locale=>:nl, :value=>"meer", :derivative_key=>"More", :key=>"word.more"}
>> "More users".t.merged_strings.last.meta_data
- => {:actual_key=>"word.user", :key=>"users", :actual_value=>"gebruiker"}
+ => {:locale=>:nl, :value=>"gebruiker", :derivative_key=>"users", :key=>"word.user"}
>> "One".t + " " + "question".t
=> "één vraag"
>> ("One".t + " " + "question".t).merged_strings
=> ["één", " ", "vraag"]
</pre>
@@ -168,12 +165,14 @@
h3. String.to_output
E9s adds the @to_output@ method to the String class. This returns the an @i18n tag@ with @HTML 5 attributes@ in which the translation meta data is provided:
<pre>
+ >> Rich::I18n::Engine.enable_enriched_output = true
+ => true
>> "More users".t.to_output
- => "<i18n data-actual_key=\"word.more\" data-key=\"More\" data-actual_value=\"Meer\">Meer</i18n><i18n data-actual_key=\"word.user\" data-key=\"users\" data-actual_value=\"gebruiker\">gebruikers</i18n>"
+ => "<i18n data-value=\"meer\" data-locale=\"nl\" data-key=\"word.more\" data-derivative_key=\"More\">Meer</i18n> <i18n data-value=\"gebruiker\" data-locale=\"nl\" data-key=\"word.user\" data-derivative_key=\"users\">gebruikers</i18n>"
</pre>
This can be very handy when implementing a CMS in which users change translations. Please note that "http://github.com/archan937/e9s-demo":http://github.com/archan937/e9s-demo uses this feature to highlight translations. Later on this will also be used in "Rich-CMS":http://github.com/archan937/rich_cms, a gem / plugin that makes inplace translating possible (please be patient for this to be released).
h3. I18n examples
@@ -243,19 +242,36 @@
This Rails gem / plugin depends on:
i18n<br>
"http://github.com/svenfuchs/i18n":http://github.com/svenfuchs/i18n
+Hpricot<br>
+"http://github.com/whymirror/hpricot":http://github.com/whymirror/hpricot (thanks Why!)
+
+Rich-CMS (optional)<br>
+"http://github.com/archan937/rich_cms":http://github.com/archan937/rich_cms
+
Formtastic (optional)<br>
"http://github.com/justinfrench/formtastic":http://github.com/justinfrench/formtastic
SeatHolder (optional)<br>
"http://github.com/archan937/seat_holder":http://github.com/archan937/seat_holder
h2. ToDo's
-* Override String interpolation (e.g. "foo #{"bar".t}") for preserving metadata (please note: by using String interpolation all translation meta data will be lost!)
+* Provide a rake task to create the Translation model and migration files
+* Use a better implementation to tackle String interpolation (e.g. "foo #{"bar".t}") to preserve meta data
* Most String inflection methods are also defined in rich_pluralization (keep it DRY)
+
+h2. E9s
+
+E9s - "http://github.com/archan937/e9s":http://github.com/archan937/e9s
+
+h3. E9s modules
+
+* Rich-CMS - "http://github.com/archan937/rich_cms":http://github.com/archan937/rich_cms
+* Rich-i18n - "http://github.com/archan937/rich_i18n":http://github.com/archan937/rich_i18n
+* Rich-pluralization - "http://github.com/archan937/rich_pluralization":http://github.com/archan937/rich_pluralization
h2. License
Copyright (c) 2010 Paul Engel, released under the MIT license