Technical Implementation Guide
We've coded and documented a full internationalizaton (i18n) implementation, so take a look and use it as a reference.
See the app & documentation
Get the source code on github
Step 1: Set up your Wordchuck project
Go to https://wordchuck.com/signup to create your account.
See detailed project setup instructions here, or watch the first half of the screencast above.
Step 2: Internationalize (i18n)
If your app is not already internationalized, we recommend you get started by adding your app's content to your Wordchuck project.
As you add content, Wordchuck will generate the proper i18n code to insert into your app. This way, there's no guessing about what needs to go where. [see example]
The i18n code for a piece of content representing the "title" for the "index" action of the "welcome" controller would look like this:
t(:title, :scope => [:welcome, :index])
In your view code, all you need to do is replace your title's content with the i18n code, like so:
BEFORE:
AFTER (in haml):
t(:title, :scope => [:welcome, :index])
AFTER (in erb):
<%= t(:title, :scope => [:welcome, :index]) %>
[hide example]
If this is your first time internationalizing an app, our Demo App is a step-by-step guide showing how to do a complete i18n implementation in Rails. You can see all of the source code for the Demo App at github.
Step 3: Install the Wordchuck Ruby Gem
Install the Wordchuck gem:
$ sudo gem install wordchuck
Create an initializer (config/initializers/wordchuck.rb) to store your project's API key:
Wordchuck.configure do |config|
config.project_key = 'whatever_your_project_key_is'
end
Your project's API key can be found on the "settings" page in the Wordchuck App.
FOR RAILS 3.x:
Add the gem to your Gemfile like so:
gem 'wordchuck'
FOR RAILS 2.x:
Add the gem to config/environments.rb like so:
config.gem 'wordchuck'
You'll also need to add the Rake task (generate.rake) to your lib/tasks folder. It can be found here.
If you don't have a locales folder in your config directory, create it. We know, we're working on it :)
Step 4: Generate your locale files
The Wordchuck gem automatically generates your locale files, including all of the latest translations for each language. To generate locale files, run the following rake task:
$ rake wordchuck:generate
Locale files are generated in the config/locales directory.
You can generate your locale files as often as you like. Each time you run the rake task, the old locale files are REPLACED with the new ones. It is important that you don't modify the locale files directly, as any manual changes will be overwritten next time the rake task is run.
Quick Start for Heroku Apps
Step 1: Internationalize (i18n)
If your app is not already internationalized, we recommend you get started by adding your app's content to your Wordchuck project.
As you add content, Wordchuck will generate the proper i18n code to insert into your app. This way, there's no guessing about what needs to go where. [see example]
The i18n code for a piece of content representing the "title" for the "index" action of the "welcome" controller would look like this:
t(:title, :scope => [:welcome, :index])
In your view code, all you need to do is replace your title's content with the i18n code, like so:
BEFORE:
AFTER (in haml):
t(:title, :scope => [:welcome, :index])
AFTER (in erb):
<%= t(:title, :scope => [:welcome, :index]) %>
[hide example]
If this is your first time internationalizing an app, our Demo App is a step-by-step guide showing how to do a complete i18n implementation in Rails. You can see all of the source code for the Demo App at github.
Step 2: Install the Wordchuck Ruby Gem
Install the Wordchuck gem:
$ sudo gem install wordchuck
Create an initializer (config/initializers/wordchuck.rb) to store your project's API key:
Wordchuck.configure do |config|
config.project_key = 'whatever_your_project_key_is'
end
Your project's API key can be found on the "settings" page in the Wordchuck App.
NOTE: If you're using Rails 2.x, you'll also need to add the Rake task (generate.rake) to your lib/tasks folder. It can be found here.
Step 3: Generate your locale files
The Wordchuck gem automatically generates your locale files, including all of the latest translations for each language. To generate locale files, run the following rake task:
$ rake wordchuck:generate
Locale files are generated in the config/locales directory.
You can generate your locale files as often as you like. Each time you run the rake task, the old locale files are REPLACED with the new ones. It is important that you don't modify the locale files directly, as any manual changes will be overwritten next time the rake task is run.
Step 4: Install the Heroku Wordchuck add-on
The Wordchuck add-on for Heroku allows you to access your Wordchuck project directly from your Heroku app's control panel.
To install:
$ heroku addons:add wordchuck
Once you install the add-on, you will see Wordchuck appear in your list of add-ons.
Setting up your Project
Update your project settings:
- Enter the Name and Url for your project.
- Confirm the Base Locale - this is the default locale for your project.
- Select the languages you want to translate your project into. Make sure you select at least one now; you can add or remove languages at any time.
- Save your project
Create your first section:
- Sections are just a way of categorizing and organizing your site's content. Some people like to organize it by controller, others like to organize it by page -- it's up to you.
- If you aren't sure what to do, we recommend creating a generic Section called "website", and putting all of your content there for now.
- Don't worry about making mistakes - you can always change your Sections and move content around in the future.
Add some content:
- The "Content Key" is used to identify the content string you are entering.
- For example, if you're entering your site's slogan, a good descriptive Content Key would be "slogan"
- The "Content" field is for the actual content that will be translated.
- For detailed documentation on how to do things like variable interpolation, named routes, ActiveRecord data values and more, visit our Demo + Documentation App.