Support for translation workflow in rails applications.
- CSV: comma separated values, a tabular data format which can be loaded into a spreadsheet package
- I18n: an abbreviation of 'internationalisation', which is the process of adding
support for multiple locales and languages to an application.
I18n
is also the name of a ruby gem which supports internationalisation in ruby applications. - interpolation: a technique used in I18n whereby data is inserted ("interpolated")
into a translated string of text, for example
Hello %{name}
would becomeHello Sarah
if the variablename
had the valueSarah
. - YAML: yet another markup language, a textual data format used for storing translation strings in rails applications
This gem provides a rails engine which adds rake tasks to manage translation files.
It is intended to be included within your rails application by referencing it
as a dependency in your Gemfile
. You will then be able to use the rake tasks
to manage your translation files and import/export translation strings.
To date it has only been tested with a rails 3.2.18 app, but it should work with later (and older) rails apps as well.
Add this line to your application's Gemfile:
gem 'rails_translation_manager'
And then execute:
$ bundle
The gem depends on your rails application environment so it would not make sense to install this gem stand-alone.
The primary usage of this gem is to support translation workflow.
Once you have installed the gem into your application as described above, the expected usage is:
-
export translations to a CSV file using:
rake translation:export:all[target_directory]
or
rake translation:export[target_directory,base_locale,target_locale]
-
send the appropriate CSV file to a translator
-
wait for translation to happen
-
receive translation file back, check it for character encoding issues
-
import the translation file using either:
rake translation:import:all[source_directory]
or
rake translation:import[locale,path]
this will generate
.yml
files for each translation -
commit any changed
.yml
filesgit add config/locale git commit -m 'added new translations'
A second feature supported by this library is the validation of interpolation keys.
The I18n library supports 'interpolation' using the following syntax:
en:
some_view:
greeting: Hello, %{name}
in this case the application can pass in the value of the name
variable.
If a translation includes an interpolation placeholder which has not been given a value by the application backend, then a runtime error will be raised.
Unfortunately the placeholder variables sometimes get changed by mistake, or by translators who are not aware that they should not modify text within the special curly braces of the interpolation placeholder.
This is obviously not great, and the validation task is intended to guard against it.
It will check all translation files and report any which contain placeholders which do not exist in the english file.
$ rake translation:validate
Success! No unexpected interpolation keys found.
A third feature is the ability to "steal" one or more locales from an existing application. This functionality works by providing a mapping file, which defines how the translation keys in the the source app's files map to those in the app the gem is installed in.
For example, given a locale file like this in the app to "steal" from:
es:
document:
type:
case_study: Caso de estudio
consultation: Consulta
and a mapping file like this:
document.type: content_item.format
running rake translation:steal[es,../other_app,mapping_file_path.yml]
will
result in the following locale file being created:
es:
content_item:
format:
case_study: Caso de estudio
consultation: Consulta
The mapping file can live anywhere, as long as the full path (including filename) is given in the rake task invocation.
The process will preserve data already in the output file if it is not referenced in the mapping, but will always override data belonging to keys that are in the mapping.
rake translation:export[directory,base_locale,target_locale]
rake translation:export:all[directory]
rake translation:import[locale,path]
rake translation:import:all[directory]
rake translation:regenerate[directory]
rake translation:validate
rake translation:steal[locale,source_app_path,mapping_file_path]
rake translation:steal:all[source_app_path,mapping_file_path]
To run the test suite just run bundle exec rake
from within the
rails_translation_manager
directory.
You will need to clone the repository locally and run bundle install
the
first time you do this, eg.:
$ git clone git@github.com:alphagov/rails_translation_manager.git
$ cd rails_translation_manager
$ bundle install
$ bundle exec rake
...
We use semantic versioning, and bump the version on master only. Please don't submit your own proposed version numbers.