i18n-docs is a ruby gem that helps you to maintain your translations files, using a Google Docs Spreadsheet, or any other csv file. This makes it easier for translators and project members to coordinate changes and updates. In addition, the standard features of Google Docs are super handy for this process: revision tracking, authorization, etc.
This gem works both in Rails and non-Rails environment. See 3. Usage for more details.
- import translations from Google Spreadsheet/Worksheet or csv files to locales yml files (one per locale)
- export translations from local locales yml files to Google Spreadsheet/Worksheet or csv files
The spreadsheet can either be a Google Drive spreadsheet worksheet or a csv file.
eg: Google Drive
Spreadsheet name: my-i18n
Spreadsheet key: 1GsK...Cjwfw (see the url https://docs.google.com/spreadsheets/d/{spreadsheet_key}/edit)
Worksheet name: numbers
| key | en | fr | de |
|---------------|-------|-------|------|
| numbers.one | one | un | eins |
| numbers.two | two | deux | zwei |
| numbers.three | three | trois | drei |
eg: csv spreadsheet
File path: config/locales/activities.yml
| key | en | fr | de |
|-------------|------|---------|--------|
| places.home | Home | Maison | Heim |
| places.work | Work | Travail | Arbeit |
| places.park | Park | Parc | Park |
This is the assumed file structure of the project locales:
locales
├── en
│ ├── numbers.yml
│ └── activities.yml
├── de
│ ├── numbers.yml
│ └── activities.yml
└── fr
├── numbers.yml
└── activities.yml
And this is an example of one of the translated file en/numbers.yml:
---
en:
numbers:
one: one
two: two
three: three
Create a configuration file called i18n-docs.yml as the following:
files:
numbers.yml: "google-drive|1GsK...Cjwfw|numbers"
activities.yml : "config/locales/activities.csv"
... etc ...
google_drive_credentials:
oauth:
client_id: "YOUR_ID_GOES_HERE"
client_secret: "YOUR_SECRET_GOES_HERE"
default_locale: 'en' # The main locale, does only count for export
locales: ['en','fr','de'] # Subset of locales to play with
google_drive_credentials: {} # Google Drive credentials (see `i18n-docs.yml`)
files: {key => value} # Files to use (see `i18n-docs.yml`)
files_only: ['activities.yml'] # Subset of filename to use
cleanup: false # Remove temporary files
tmp_dir: 'tmp' # Temporary upload/download directory, default: './tmp/i18n-docs/'
locales_dir: 'i18n' # Final locales directory, default './_i18n' or './locales'
single_locale_file: true # Deal only with one file per locale (no locale subdirectories)
include_locale_key: true # Include the locale as a key at the root of the locale file
force_fallback: true # Force all translations to have a value, default: false
# Fallback chain 1.locale, 2.default locale, 3.humanized key
# Future work
logger_level: 0 # Verbose?
format: 'yml' # .yml or .json ? default: .yml
In this section, locale files are tied with translation spreadsheets.
Google Doc spreadsheet is identified by its spreadsheet key and worksheet name with the following format:
google_drive|{spreadsheet_key}|{worksheet_name}
You can pull information from some local files by giving directly an url from where the gem is run (as activities.yml in the example).
To get Google OAuth client_id and secret, you can follow this link: https://console.developers.google.com/project
The first time you'll run i18n-docs, it will open a webpage with Google asking you to authorize the application. After having accepted, you'll get a authorization key.
Copy and paste the key in the prompt. The key will be saved for future calls in .i18n-docs-access-token.
There's actually different ways of calling these options. You can define them:
- when calling a method in ruby, by passing options as a hash (eg:
I18nDocs::TranslationsManager.import_translations({'locales_dir' => '_i18n'})) - when running a rake task, by setting env variables (eg:
locales_dir=_i18n rake i18n:export_translations) - or simply by writing them in
i18n-docs.yml
The only options that is not in the config file is the directory where to find the config file!
You can specify it as a ruby or an env option with the key i18n-docs-path.
By default, it will look in the current directory, or in the config directory for a Rails app.
With single_locale_file=true (and with only one file specified), you'll get the following file structure:
locales
├── en.yml
├── fr.yml
└── de.yml
With include_locale_key=false, you'll get the following locale files eg en/numbers.yml:
---
numbers:
one: one
two: two
three: three
Note that en: has disappeared from the top.
With force_locale=true, all blank values will be force to be present:
| key | en (default) | fr | de |
|-------------|--------------|--------|------|
| places.home | Home | Maison | Heim |
| places.work | Workplace | | |
| places.park | | | |
becomes
| key | en (default) | fr | de |
|--------------------|--------------|-------------|-------------|
| places.home | Home | Maison | Heim |
| places.work | Workplace | Workplace | Workplace |
| places.castle_park | Castle park | Castle park | Castle park |
Note that locales are defaulting to the default locale, and then to the humanized key.
The official i18n-docs gem lives here https://rubygems.org/gems/i18n-docs. You can refer to it via:
group :development do
gem 'i18n-docs'
gem 'i18n-docs', '~> 0.0.7'
end
But because a lot of development had happened lately which hasn't been merged into local-ch/i18n-docs yet, you may want to reference a commit directly on github, following http://bundler.io/git.html.
group :development do
gem 'i18n-docs', :github => 'AntoineInsa/i18n-docs',
gem 'i18n-docs', :github => 'AntoineInsa/i18n-docs', :branch => 'master'
gem 'i18n-docs', :github => 'AntoineInsa/i18n-docs', :tag => 'v0.0.8'
gem 'i18n-docs', :github => 'AntoineInsa/i18n-docs', :ref => 'b2ea22e18b3'
end
You can as well clone/download the project, and use it locally:
group :development do
gem 'i18n-docs', :path => '~/Sites/i18n-docs'
end
Add the gem to your Rails project:
gem 'i18n-docs', :github => 'AntoineInsa/i18n-docs'
Let Rails know what locales you will be using. Add this to config/application.rb:
module Web
class Application < Rails::Application
# add yml path
config.i18n.load_path += Dir[Rails.root.join('config', 'locales', '*', '*.yml').to_s]
# locals to support:
config.i18n.available_locales = [:en,:de,:it,:fr]
end
end
This defines which languages and translation files to import from a Google Spreadsheet. The content of the spreadsheets will be stored under config/locales/.
The following rake tasks are added by the gem to your Rails project:
rake i18n:export_translationsExport all translations files to spreadsheets (Google Drive and/or local files) (the defined default locale is the reference for files to export)rake i18n:import_translationsDownload translations from spreadsheets (Google Drive and/or local files) and save them into YAML files.
This gem is currently in use and tested with Rails 3.1. It probably works with other 3.x versions, but probably not 2.x at the moment.
Pick-up any directory, add a i18n-docs.yml file (see 2.).
Add a Gemfile:
source "https://rubygems.org"
gem 'i18n-docs', :github => 'AntoineInsa/i18n-docs'
Add a i18n-docs.rb:
#!/usr/bin/env ruby
require 'rubygems'
require 'i18n-docs'
# To import translations
I18nDocs::TranslationsManager.import_translations()
# To export translations
# I18nDocs::TranslationsManager.export_translations()
You may have to install:
- Rbenv (https://github.com/sstephenson/rbenv)
- RubyGems (https://rubygems.org/pages/download)
- Bundler (http://bundler.io/)
And simply execute the file by running bundle install the first time, and bundle exec ruby i18n-docs.rb! Et voilà!
Make it work outside of a Rails environment
Use i18n-docs.yml (old translations.yml) configuration file for Google OAuth credentials.
Upgrade to OAuth before Google deprecation deadline.
Update docs, license. Push to Rubygems.org.
Open sourced: changed name and description.
Removed loading of awesome_print from the rake task. It was breaking download.
- Fork it ( https://github.com/AntoineInsa/i18n-docs/fork )
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Run the tests (
bundle exec rspec specorrake) - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
This gem is sponsored by local.ch. It is licensed under the MIT license. If you're a ruby developer and want to work with us in Switzerland, please check out our jobs page.
This gem has been improved by Attendease as well, from Vancouver, BC, Canada.