To enable your new translation environment the following steps are necessary:

1. Prepare your application for internationalization
2. Create an Engine Yard environment
3. Install the PhraseApp Add-on
4. Upload your existing translations
5. Start translating

This manual explains how to use PhraseApp with a Ruby on Rails application hosted on Engine Yard and assumes you're using the common YAML file based i18n backend. Other application stacks might work similar.

1. Prepare your application for internationalization

In order to use PhraseApp with your application it must be localized. That is, all translatable strings must be replaced with keys and wrapped in the t() method call.

For more information visit the i18n Rails Guide: http://guides.rubyonrails.org/i18n.html

2. Create an Engine Yard translation environment

2.1 Add a new application

Unless the application you want to translate with PhraseApp is configured in your Engine Yard account, you will need to create it first:

Log in to your Engine Yard panel and click "Add an Application":

Enter the details of your application, such as the name, the location of its repository and its Rails version. In this example we use a Demo Todo application:

Add the application to your Engine Yard account by clicking "Create Application".

2.2 Start a new Engine Yard environment

The PhraseApp translation solution is meant to run on a separate staging/translation environment or in development but never in your production setup.

Thus you should start a separate environment for your Engine Yard application. In this example we use the staging Rails environment but any other will work as well.

To create a new environment, go to your application in your Engine Yard control panel and click "Create New Environment". In case you just created the application you should already see the form to create the environment.

Give your new environment a name (e.g. "Translation") and select staging as the Rails environment or use a custom one (e.g. translation). Fill out the technical details about your new environment according to the setup you prefer and create the environment by clicking the "Create Environment" button on the bottom of the page.

3. Install the PhraseApp Add-on

3.1 Activate the Add-on

After your staging environment is configured you should activate the PhraseApp add-on for the new environment. Visit the Add-on store for the environment by clicking "New Add-on" on the bottom of your environment configuration page:

Choose the "PhraseApp" add-on and sign up for the service by clicking "Set it up".

Next, activate it for the appropriate environments. This will create an access_token and project_id variable that can then be used in your app.

You can create, manage and revoke access tokens in your profile settings or via the Authorizations API.

You can find your access token and project id on the bottom of your Engine Yard application environment settings page in the "Add-on" section.

Learn more about managing Add-ons in the official Engine Yard documentation

3.2 Add the phraseapp-in-context-editor-ruby gem

Next, add the phraseapp-in-context-editor-ruby gem to your Rails application by adding it to your Gemfile:

group :staging do
  gem 'phraseapp-in-context-editor-ruby'
end

and install it via Bundler:

$ bundle install

3.3 Initialize the phraseapp-in-context-editor-ruby gem

Use the Rails generator task to initialize the gem for your Rails app:

$ bundle exec rails generate phraseapp_in_context_editor:install --access-token=YOUR_PHRASEAPP_ACCESS_TOKEN --project-id=YOUR_PHRASEAPP_PROJECT_ID

Remember: You can find your access token and project id on your application environment settings page.

Open the phraseapp_in_context_editor.rb initializer file in config/initializers and replace the access token and project id with a more flexible call to the env setting provided by the Engine Yard addon:

PhraseApp::InContextEditor.configure do |config|
  ...
  config.enabled = (ENV['RACK_ENV'] == 'staging')
  config.access_token = EY::Config.get(:phraseapp, "access_token")
  config.project_id = EY::Config.get(:phraseapp, "project_id")
  ...
end

3.4 Add the Javascript

Add the Javascript snippet to your application using the phraseapp_in_context_editor_js helper:

<head>
  ...
  <%%= phraseapp_in_context_editor_js %>
  ...
</head>

4 Upload your existing translations

Besides managing your projects and locale files through the web interface you can also use the PhraseApp Command Line Client. Follow the install and configuration instructions and use the client to push your locales:

$ phraseapp push

5. Start translating

5.1 Deploy your app

Once everything is set up you can deploy your application to the new translation/staging environment. After that, just visit your application in the browser. You should now see the PhraseApp login window of the In-Context-Editor.

5.2 Create the first translator user

To create the first user to work with your new translation environment simply sign in with the "View Dashboard" link within your Engine Yard config panel for the PhraseApp add-on. This link will sign you into your PhraseApp account where you can manage your projects, translations and users.

After signing in, visit the user management panel by follow "Account" and visit "User Management". Create your first (actually second) user manually by clicking "Add User". Make it a manager user, that is a user with access to all of your projects. The user will instantly receive a password link via email.

You can use those these user credentials now to log into PhraseApp Translation Center and to log into your your In-Context-Editor installation on your translation environment.

5.3 Translate your app

With your new In-Context-Editor in place and your first translator user created, you can now start translating your app. You will soon notice how easy it is to edit translations on your site and how the quality of your translations will improve with the context information that is now available through the editor.

Congratulations on a new and improved translation experience with PhraseApp and Engine Yard!

5.4 Deploy your new translations

Once you have done all the translation work you will most likely want to ship your new translations to your production environment:

1. Download your updated locale files from PhraseApp with the PhraseApp Command Line Client:

   $ phraseapp pull
   

2. Run the tests for your app (if available)

3. Commit the new/updated files to your repository

4. Deploy the new revision of your app to your Engine Yard production environment

More Information

• ToDo (Sample application with a working integration for use on Engine Yard) https://github.com/phrase/todo
• PhraseApp Documentation: https://phraseapp.com/docs
• PhraseApp Add-on: https://www.engineyard.com/addons/phraseapp