Using PhraseApp on Heroku

This article covers the integration of PhraseApp with a Ruby on Rails/Sinatra application on Heroku.

PhraseApp is also available as a Heroku addon.

If you haven’t done so already, we recommend setting up a separate staging environment to use the PhraseApp In-Context-Editor with your Heroku application. This staging environment will be the place for your translators to translate your website content.

Of course, you can also use your local development environment to see how PhraseApp integrates with your application. If you plan to do so, just replace the staging environment with your development environment in the following steps.

This article covers the integration of PhraseApp with a Ruby on Rails application on Heroku. Other frameworks might work similar.

Integrate PhraseApp to your application

Follow these easy steps to get PhraseApp running on Heroku:

  1. Provision the Add-on
  2. Add and configure the Add-on
  3. Deploy your application to your staging environment


PhraseApp can be attached to a Heroku application via the CLI:

$ heroku addons:add phrase
-----> Adding phrase to sharp-mountain-4005... done, v18 (free)

Once the add-on has been provisioned, a PHRASE_ACCESS_TOKEN and a PHRASE_PROJECT_ID setting will be available in your app configuration. It contains your oauth access token which allows you to connect to the PhraseApp API:

$ heroku config | grep PHRASE_ACCESS_TOKEN
PHRASE_ACCESS_TOKEN    => 4bd4474ce91066bb53d23f49d61f8747

It also contains the project id to access your automatically created project in PhraseApp:

$ heroku config | grep PHRASE_PROJECT_ID
PHRASE_PROJECT_ID    => ba0c61b5346588a9f4109c263572e305

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


After you have set up a staging environment and provisioned the add-on, you need to prepare your application to connect with PhraseApp:

Add the gem

Add the phraseapp-in-context-editor-ruby gem to your staging environment:

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

and install it by executing the bundle command:

$ bundle install
Ruby on Rails

Install the phraseapp-in-context-editor-ruby gem by executing the Rails generator:

$ bundle exec rails generate phraseapp_in_context_editor:install --access-token=YOUR_PHRASE_ACCESS_TOKEN --project-id=YOUR_PHRASE_PROJECT_ID

Open the phraseapp_in_context_editor.rb initializer file in config/initializers and replace the auth token with a more flexible call to the env setting provided by the Heroku addon:

PhraseApp::InContextEditor.configure do |config|
  config.enabled = (ENV['RACK_ENV'] == 'staging')
  config.access_token = ENV['PHRASE_ACCESS_TOKEN']
  config.project_id = ENV['PHRASE_PROJECT_ID']

Add the Javascript

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

  <%= phraseapp_in_context_editor_js %>

Set the load path

Your application needs to know that it should use the PhraseApp locales. This can be achieved by setting the i18n load path in your application config.

Pushing existing locale files

Besides managing your projects and locale files through the web interface you can also use the PhraseApp Command Line Client to push your locales:

$ phraseapp push

Deploying the application

You can now deploy your application to your staging system:

$ git push staging master

Once deployed, open it in your browser:

$ heroku open

You should now see your application ready to be translated with the PhraseApp In-Context-Editor.

Publishing translations

After you have finished translating you need to deploy the new localization files to your production system:

$ phraseapp pull
$ git add ./config/locales
$ git commit -m "added new translations"

You can now push the changes to your production repository and deploy your production system with your new translation content:

$ git push heroku master


You can remove the PhraseApp add-on via your Heroku CLI:

Warning: This will destroy your PhraseApp account and all associated data!
$ heroku addons:remove phrase
-----> Removing PhraseApp from sharp-mountain-4005... done, v20 (free)

Before removing PhraseApp please make sure that you have downloaded all translations from your account. After deprovisioning your account will be shut down and your account data will be deleted.

More resources