1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258
|
= I18n Inflector
<b>i18n-inflector version <tt>2.6.6</tt></b> (<b><tt>Little Kózka</tt></b>)
* https://rubygems.org/gems/i18n-inflector
* https://github.com/siefca/i18n-inflector/tree
* mailto:pw@gnu.org
== Summary
This library contains a backend module for I18n that adds some extra
functionality to standard backend. It overwrites the translate method
in a way that it will interpolate additional inflection tokens present
in translations.
== Synopsis
require 'i18n-inflector'
I18n.translate( 'to_be', :number => :singular,
:tense => :past,
:person => 2 )
#=> You were here
I18n.translate('welcome', :gender => :female)
#=> Dear Lady
== Why?
You can use I18n Inflector to (relatively easy) create
translations for highly inflected languages (like those
belonging to Slavic language family). You can also use it
in translation services that may operate on sentences
instead of exact words.
== When?
It is intended to be used in a web projects or other projects where
translations are performed by many people, yet there is a need to
inflect sentences with some external variables. To achieve similar
functionality lambdas can be used but including many Proc objects
might be considered unsafe or memory consuming.
See i18n-inflector-rails[https://rubygems.org/gems/i18n-inflector-rails] if
you need Rails integration.
== How?
I18n Inflector lets you build you own inflection patterns
contained in translation entries. The patterns may contain simple
conditions and tokens, which combined with parameters
passed to +I18n.translate+ method can produce inflected
strings.
* See {USAGE}[http://rubydoc.info/gems/i18n-inflector/file/docs/USAGE] for detailed information about the usage.
* See {EXAMPLES}[http://rubydoc.info/gems/i18n-inflector/file/docs/EXAMPLES] for examples.
* See {whole documentation}[http://rubydoc.info/gems/i18n-inflector/] to browse all documents.
== Features
* Inline inflection using patterns in translation data.
* Key-based inflection using individual inflection keys.
* Definable inflection kinds and tokens.
* Easy to use public API for inflection data.
* Configurable using special scope of translation data.
* Lazily evaluated Proc and Method objects as inflection options.
* Complex patterns support; inflection by more than one kind at a time.
* Negative matching, aliases, default tokens, token groups and more…
== Description
The I18n Inflector extends the translate method from I18n in a way that
it will interpolate additional inflection tokens present in
translations. These tokens may appear in *patterns* which are contained
within <tt>@{</tt> and <tt>}</tt> symbols. Configuration is stored
also in translation data, in a scope <tt><locale>.i18n.inflections</tt>,
where <tt>locale</tt> is a locale subtree.
You can create your own inflection kinds (gender, title, person, time, author, etc.)
of tokens to group them in a meaningful, semantical sets. That means you can
apply Inflector to do simple inflection by a gender or a person, when some
language requires it.
It adds the +inflector+ object to the default backend so you can use many
methods for accessing loaded inflection data at runtime, or to set up global
switches that are controlling the engine.
== Short example
Example configuration which uses translation data:
en:
i18n:
inflections:
gender:
f: "female"
m: "male"
n: "neuter"
female: @f
male: @m
default: n
Example translation data:
en:
welcome: "Dear @{f:Lady|m:Sir|n:You|All}!"
@same_but_as_key:
f: "Lady"
m: "Sir"
n: "You"
@prefix: "Dear "
@suffix: "!"
@free: "All"
=== Note about YAML parsing
The example above is not compatible with Psych parser, which is used
by Rails 3. There are two ways to solve that problem.
First is to change a YAML file and replace any value that has
special meaning with a symbol:
en:
i18n:
inflections:
gender:
f: "female"
m: "male"
n: "neuter"
female: :@f
male: :@m
default: :n
Second way is to use other parser by adding to +config/boot.rb+:
require 'yaml'
YAML::ENGINE.yamler = 'syck'
== New features
From version 2.1.0 the Inflector supports so called named patterns,
which can be used if there is a need to be strict and/or to
use the same token names but assigned to different kinds. Example:
welcome: "Dear @gender{f:Lady|m:Sir|n:You|All}"
From version 2.2.0 the Inflector supports complex patterns,
which can be used to inflect some sentence or a word by more
than a one kind. That might be very helpful for highly inflected
languages. An example pattern:
welcome: "Dear @gender+number{f+s:Lady|f+p:Ladies|m+s:Sir|m+p:Gentlemen|All}"
== Requirements
* i18n[https://rubygems.org/gems/i18n]
* rake[https://rubygems.org/gems/rake]
* rubygems[http://docs.rubygems.org/]
* bundler[http://gembundler.com/]
== Download
==== Source code
* https://github.com/siefca/i18n-inflector/tree
* <tt>git clone git://github.com/siefca/i18n-inflector.git</tt>
==== Gem
* https://rubygems.org/gems/i18n-inflector
== Installation
* <tt>gem install i18n-inflector</tt>
== Detailed example
<b>YAML:</b>
en:
i18n:
inflections:
gender:
f: "female"
m: "male"
n: "neuter"
o: "other"
default: n
welcome: "Dear @{f:Lady|m:Sir|n:You|All}"
<b>Code:</b>
I18n.t('welcome')
# => "Dear You"
I18n.t('welcome', :gender => :m)
# => "Dear Sir"
I18n.t('welcome', :gender => :unknown)
# => "Dear You"
I18n.inflector.options.unknown_defaults = false
I18n.t('welcome', :gender => :unknown)
# => "Dear All"
I18n.t('welcome', :gender => :o)
# => "Dear All"
I18n.inflector.options.excluded_defaults = true
I18n.t('welcome', :gender => :o)
# => "Dear You"
== More information
* See {I18n::Inflector::API} class documentation for detailed information about the API.
* See {I18n::Backend::Inflector} module documentation for detailed information about the internals.
== Tests
You can run tests both with
* <tt>bundle exec rake test</tt> or just <tt>bundle exec rake</tt>
* run <tt>bundle exec rake testv4</tt> to test with version 4 of I18n
* run a test file directly, e.g. <tt>ruby -Ilib -Itest test/inflector_test.rb</tt>
== Common rake tasks
* <tt>bundle exec rake bundler:gemfile</tt> – regenerate the +Gemfile+
* <tt>bundle exec rake docs</tt> – render the documentation (output in the subdirectory directory +doc+)
* <tt>bundle exec rake gem</tt> – builds package (output in the subdirectory +pkg+)
* <tt>bundle exec rake test</tt>, <tt>bundle exec rake testv4</tt> – performs tests
* <tt>bundle exec rake Manifest.txt</tt> – regenerates the +Manifest.txt+ file
* <tt>bundle exec rake ChangeLog</tt> – regenerates the +ChangeLog+ file
== Credits
{Heise Media Polska}[http://www.heise-online.pl/] supports Free Software and has
contributed to this library by paying for me to eat when I've been coding.
== License
Copyright (c) 2011,2012 by Paweł Wilk.
i18n-inflector is copyrighted software owned by Paweł Wilk (pw@gnu.org).
You may redistribute and/or modify this software as long as you
comply with either the terms of the LGPL (see {file:docs/LGPL}),
or Ruby's license (see {file:docs/COPYING}).
THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE.
|