1. Help Center
  2. Phrase for developers
  3. Add-ons, plug-ins, libraries and tools

Using Phrase on Heroku

Learn how to integrate Phrase with a Ruby on Rails or Sinatra application on Heroku.

Phrase works great with platform services like Heroku. We offer plugins that you can integrate into an existing hosting setup with a few clicks.

Phrase is also available as a Heroku add-on.

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

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

This article covers the integration of Phrase with a Ruby on Rails application on Heroku. However, other frameworks may work similarly.

Integrate Phrase into your application

There are three basic steps to getting Phrase running on Heroku:

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


You can attach Phrase to a Heroku application using the CLI:

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

Once the add-on has been provisioned, PHRASE_ACCESS_TOKEN and PHRASE_PROJECT_ID settings will be available in your application’s configuration. The first setting contains your OAuth access token, which allows you to connect to the Phrase API:

$ heroku config | grep PHRASE_ACCESS_TOKEN
PHRASE_ACCESS_TOKEN    => 4bd4474ce91066bb53d23f49d61f8747

The second setting contains the project ID needed to access your automatically created project in Phrase:

$ heroku config | grep PHRASE_PROJECT_ID
PHRASE_PROJECT_ID    => ba0c61b5346588a9f4109c263572e305

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

Connect to Phrase

After setting up a staging environment and provisioning the add-on, inprepare your application to connect to Phrase:


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 access token with a more flexible call to the ENV setting provided by the Heroku add-on:

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 Phrase locales. To achieve this, set the internationalization load path in your application’s configuration.

Pushing existing locale files

Besides managing your projects and locale files through the web interface, you can also use the Phrase Client to push your locales from the command line:

$ phraseapp push

Deploy 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 Phrase In-Context Editor.

Publish translations

When your translations are ready, you can 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 newly translated content:

$ git push heroku master

If you need to remove the Phrase add-on

You can remove the Phrase add-on using the Heroku command line.
Warning: Removing the add-on will permanently delete your Phrase account and all associated data.

$ heroku addons:remove phrase
-----> Removing PhraseApp from sharp-mountain-4005... done, v20 (free)

Before removing the Phrase add-on, please be sure to download all translations from your account. After removing the add-on, your account will be shut down and your account data will be permanently deleted.