i18n
If you only desire to provide a translation then I think you primarily need to read the sections on using Tolk, Email notifications and static files, Rails translations, and Javascript. You will still need to have a development instance of Bibapp to use. You may also want to contact the Bibapp list and let us know that you're doing a translation so that we can get any other things that may be needed in order.
If you are involved in more of the details than that then the rest of this page may be of interest as well. If you intended to edit strings through a text editor or IDE then you'll want to make sure that you (and it) have a basic understanding of YAML.
In either case don't hesitate to ask any questions on the Bibapp mailing list in Google Groups.
Naturally after you have done a translation we'd be very happy to include it in Bibapp. We'd be even happier if you continue to maintain it as Bibapp evolves.
Inventory of files/directories needed for translation
Because of some of the changes necessary to make Bibapp version 2.0.0 the Tolk functionality is currently disabled. It is planned to reintegrate it when we can. You can still do translations directly using the .yml files, etc.
You'll need a development installation of Bibapp. This has built into it a gem called Tolk which will let you do translation from your development instance.
To set it up, make sure that your development bundle of gems is up to date. If you do:
bundle exec gem list
you should see 'tolk' in the list. If this is the first time you're using tolk you need to set up a few things:
rake tolk:setup
This will create a few tables in your development database and import any translation information that already exists in config/locales.
Now if you start up your local development Bibapp instance and navigate to http://localhost:3000/tolk you'll see the translation interface. You can add a locale here or go to an existing locale. Once you go to a locale you get a web interface which allows you to add new translations, view completed translations, view translations that have changed (more about that momentarily), search for translations (note - this is case sensitive!) in either English or the target locale, etc.
Once you've entered some translations here, what happens? Tolk stores these translations in the database, but the files in config/locales remain the canonical source of the translations, so there are rake tasks to move things back and forth. Note: the en.yml file is special (en is called in Tolk terms the 'default locale'). This will not write things back out to that. The English translation serves as the reference for what keys are supposed to exist, etc. Developers should always add necessary keys to this file when working on Bibapp views and so forth. The rake procedures below will then make these keys known (or if they are removed unknown) to the other locales.
rake tolk:dump_all
This takes all of the translation information in the database and dumps it to files in config/locales. So after you do translation you'll want to run this task to get new your_locale.yml files that can go back into version control. Remember that Tolk is just a translation tool - the application actually uses the .yml files to look up the translations, so you must do this part and get the config/locales/your_locale.yml file into version control.
rake tolk:sync
This synchronizes the English translations in the database with those in the en.yml file. So run this after updating that file (either as you develop or from version control). As part of this procedure Tolk will remove keys that are no longer used, note new keys for translation, and notice any English keys whose values have changed (these will then be made available through the web interface in case they require re-translation).
rake tolk:import
This will attempt to import information from any locale except the default locale. So if you've done translation not through Tolk this would let you import it into the Tolk framework. Or, say you are cooperating with someone else to do a translation using Tolk locally. You might do some translations, dump them with 'rake tolk:dump_all', and commit them to version control. The other person could then pull from VC, merge with any work he had already done, and then use 'rake tolk:import' to put your changes into the database, continue working, and repeat the process. Note that Tolk seems to alphabetize all of the keys at each level, so this kind of merge should be easy.
Special notes:
- Translations that have keys starting with 'i18n' are 'meta' information of a sort. The only such key now is i18n:language:name - this should be set as the name of the language corresponding to the locale (e.g. en => English, de => Deutsch). It should not be a translation of the English value 'English'.
- Translations that have keys starting with 'jsperanto' are used by Javascript (not Rails) code. A note will show up on the right side about this. There is a slightly different interpolation syntax - see the Javascript/general section for details.
- At present when using Tolk we really do assume that you are working on a development instance of Bibapp with the default locale set to English (en). We assume that you'll make the translation files there and then move them over to your production server (and hopefully submit them to us for inclusion in Bibapp!). We can't assure what will happen if you do things differently. There have been requests to make Tolk handle the text more generally, but that's beyond the scope of what we can do at present, although we will be keeping it in mind as a possibility.
Some files are large and mostly static. These require individual translation.
Since the notifications sent by email tend to be relatively large, they are not handled with the .yml locale files. Instead we directly create views for them. There are two mailers: Notifier and UserMailer. The notifications views are in app/views/notifier and app/views/user_mailer. For a new locale each view file should be copied with the appropriate locale and translated as a whole. E.g. if creating the 'de' locale, then for app/views/user_mailer/activation.html.erb one should translate the contents in a new file called app/views/user_mailer/activation.de.html.erb.
Note that any text that is in the actual mailer class as opposed to a template will be handled in the main translation file in the common section.
In public there are some files used when there are http errors. These are 404.html, 422.html, and 500.html. These should be translated directly in public, inserting the locale into the file name. E.g. for the de locale you would translate 404.html into 404.de.html.
Other static pages used by Bibapp live in public/static/locale-code. The master list is then in public/static/en. To translate for the de locale you would copy all files from this directory into public/static/de and then translate them. You should not change the file names for these.
We use the rails-18n gem to provide translations internal to Rails. See https://github.com/svenfuchs/rails-i18n. If there is no translation there or if you wish to customize you can put a file in config/locales/rails (if you're making a new translation best to contribute it back to rails-18n and have it included that way).
##Personalizations
config/personalize.rb will now contain only information that does not require translation. Things that were in personalize.rb that require translation (e.g. the $SHERPA_COLORS) will now appear in the files in config/locales/personalize/. There is an English example file, en.yml.example to help you get started. Note that the files you create from this are specific to each installation and hence should not go into general version control (of course if you run your own fork you can do what you like). So these translations need to be done by the organization installing a particular instance of Bibapp, not someone doing a general translation for a new locale. (If you are translating for a new locale, we would be interested in having a new example file for that locale, however.)
Tolk will ignore any files in this directory.
If you require help with any of the following please just post to the Bibapp Google Group ( http://groups.google.com/group/bibapp) and someone will help you.
I've begun an i18n branch which is based on some initial efforts by Claudia Jürgen. To work on this please fork the project on Github, clone your fork to a local copy, and work on the i18n branch (or your own local branches of it there). Push your changes back to your Github fork and send a pull request (of your i18n branch to the i18n branch of Bibapp/Bibapp). In addition, it would be helpful for you to set up this repository as a remote and occasionally (e.g. after we've merged your pull request) merge its i18n into your work. This way you'll be getting the latest work anyone has been doing on i18n, and also the latest changes to the master branch, which is not internationalized yet but which will still be undergoing changes that require internationalization.
As per Claudia Jürgen's recommendation we'll try to have all the Bibapp localization information for each locale in a single file in config/locales. E.g. en.yml will have the English translations, de.yml German, etc. This is a bit less ideal than the structure described in section 3.4 of http://guides.rubyonrails.org/i18n.html (or an even finer structure) from a development perspective, but she feels that this will make things easier on translators. For (non-English) Rails localization information there will be one file for each locale in config/locales/rails.
Within these files there should be a more or less standard hierarchical set up as per the guide referenced above and explained more thoroughly below.
Each .yml file should have its keys organized alphabetically at each level. If you use Tolk to write out the files this will happen automatically. If you're too lazy to do this you can work on the file and when you're done start up a console, read in your file with YAML.load_file and then write it out again using ya2yaml which will automatically do this.
The main translation file will have a variety of sections:
####App
This section is for translations that are useful across the application but that don't really fall logically under something like a model or model attribute:
en:
app:
search: "Search" ...
####Common
This will serve two primary purposes. It is a location for strings that occur in a controller, helper, or mailer. E.g. strings for the AdminController or AdminHelper would go in en:common:admin.
It is also a way to group strings that have a common theme and are widely useful in the application. In that case it's up to the developer's judgement whether this or app is a more logical place.
en:
common:
contributorships:
key1: 'translation 1'
...
groups:
key1: 'translation 1'
etc.
####Views
Another reason to have the previous strings under en:common: instead of directly under en: is to keep those keys free to work with the standard Rails i18n conventions for views (to make lazy lookup work - but see note below). Note that for partials you leave the leading '_' off of the key name:
en:
controller_name:
view_name:
key1: 'translation 1'
Important - note that using internal layouts with a block does not interact nicely with the 'lazy lookyup' conventions. So inside the following sort of construction you'll need to use the full key:
= render :layout => 'layouts/main_body_no_h2' do
%p #{t('full.key.here')} # t('.here') will not work
####Models
We'll also use the standard set-up for translating model names and attributes:
en:
activerecord:
models:
work: 'Work'
attributes:
work:
title_primary: 'Title Primary'
etc.
Normally we'll prefer using the inline ruby insertion syntax of Haml when possible, i.e. something like:
%p #{t('translation.key')}
is mildly preferred to:
%p= t('translation.key')
However, if it's appreciably easier to use the latter syntax or if your IDE or other tool support uses the second form then that's fine.
Note: the IDE I use has some refactoring support, but likes to refactor like this in some cases:
%p = t('translation.key')
That will not have the desired effect.
I've added a rake task that lists missing keys. I think it reports some that are irrelevant, but it will likely be useful in any case.
bundle exec rake i18n:missing_keys
Some plugins that we use may have their own i18n mechanisms, which we'll detail below.
For general Bibapp javascript we're using the JSperanto i18n plugin to jquery. You'll notice that there is a section of the Rails locale file with the key "jsperanto". Everything in this section is a translation to be used with javascript. Translate them just like the rest of the values except use the interpolation syntax:
"String with __key__ interpolated"
When Bibapp starts up it will pull all of the values out of this section for all available_locales and transform them into the form that JSperanto works, writing these transformed files to public/javascripts/translations. The values from en.yml go to en.json, etc.
We use the DataTables widget for javascript tables. There is support for internationalizing this. There are a bunch of language plug-ins at http://www.datatables.net/plug-ins/i18n. To use one, copy its text into public/datatables/[locale].txt.
To enable a view that is using datatables to be internationalized, include locale.js. This has a function (datatables_language_url) that will read the requested url out of the page (Bibapp stores it in a meta-tag) and create the correct URL for the browser to fetch with the DataTables translations. Set the sUrl attribute of the oLanguage configuration option for the datatable to the value of this function. The plugin handles things from there.