This add-on is operated by Dynport GmbH

Easy and Powerful Localization for Web and Mobile Applications


Last Updated: 19 March 2014

Table of Contents

PhraseApp allows you to edit your translations directly on your site without having to deal with localization files at all. This makes handling your whole translation process easy as pie. Use the frontend editor to edit content directly on your site or manage your translations with the powerful PhraseApp backend!

Using PhraseApp, translations of your sites improve automatically since the translator knows exactly about the context the text is used in. While translating, you can see immediately if the length of the text fits in the given space.

Free your developers from having to deal with the content and structure of localization files and automate your translation workflow.

PhraseApp can be used with a variety of languages and frameworks.

A sample Sinatra application is available at Github

Provisioning the add-on

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_AUTH_TOKEN setting will be available in the app configuration. It contains your authentication token that enables you to connect to the PhraseApp service:

$ heroku config | grep PHRASE_AUTH_TOKEN
PHRASE_AUTH_TOKEN    => 23adcxBahs7192Kdbcg1

Using with Ruby

PhraseApp should be integrated in an own staging environment. It is not recommended to include PhraseApp in your production environment since that would render the PhraseApp editor and let your visitors edit your site content.

If you haven’t done so already, we recommend you to set up a staging environment as explained in the official Heroku documentation. The staging environment will be the place for your translators to translate your website content. Of course, you can also use your local develoment environment to see how PhraseApp integrates with your application. If you plan to do so, simply replace the staging with your development environment in the following steps.

The following integration guide assumes your application uses bundler for gem dependency management.

Add the gem

Add the phrase gem to your staging environment:

group :development, :staging do
  gem 'phrase'

and install the gem with the bundle command:

$ bundle install

If you are using Sinatra, you might have to require PhraseApp in your app file:

if ENV['RACK_ENV'] == 'staging'
  require "phrase"

This will load PhraseApp when you visit your application in staging environment.

Initialize PhraseApp

First you need to tell PhraseApp to start automatically with your application and provide the authentication token. You can do this by adding the following two lines to an initializer (Rails) or just in your main application file:

Phrase.enabled = true
Phrase.auth_token = ENV['PHRASE_AUTH_TOKEN']

Now initialize PhraseApp with the auth token you received after adding the PhraseApp addon to your application:

$ bundle exec phrase init --secret=YOUR_AUTH_TOKEN --default-locale=en

This will generate a .phrase config file in your project root that includes your secret key. We recommend adding it to your .gitignore file:


Next, upload the existing locale files from your app:

$ bundle exec phrase push ./config/locales/

PhraseApp now knows about your locales and the keys in your application. To enable the PhraseApp In-Context-Editor features, simply add the javascript to your application layout:

var phrase_auth_token = '<%= ENV['PHRASE_AUTH_TOKEN'] %>';
(function() {
  var phraseapp = document.createElement('script'); phraseapp.type = 'text/javascript'; phraseapp.async = true;
  phraseapp.src = ['https://', '', new Date().getTime()].join('');
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(phraseapp, s);

In order to tell the i18n gem about the new locales that should be used in production you have to configure the load path as well. When using Rails you can set the load path in your production.rb:

config.i18n.load_path = Dir[Rails.root.join('phrase', 'locales', '*.yml').to_s]

If you’re using Sinatra, you probably want to set it in the file:

if ENV['RACK_ENV'] == 'production'
  I18n.load_path = Dir[File.join(File.dirname(__FILE__), 'phrase', 'locales', '*.yml').to_s]
  I18n.load_path = Dir[File.join(File.dirname(__FILE__), 'config', 'locales', '*.yml').to_s]

Deploy application to staging environment

To finally get a look at PhraseApp you simply have to deploy the application to your staging system:

$ git push staging master

and open it in the browser:

$ heroku open

You now should see your application with the PhraseApp in-place editor on top of it. To create your first user with translation privileges, you have to log into phrase:

$ heroku addons:open phrase
Opening phrase for sharp-mountain-4005…

After logging in, you can access the user management under the “Account” menu. Simply create a user with an email address and password of your choice. You can now edit your text content right on the site!

Deploy translations

After you have finished translating your site, you will need to push the new translation files to production. In order to do so, you will first have to download them from PhraseApp and add them to your project:

$ bundle exec phrase pull
$ git add ./phrase/locales
$ git commit -m "added new translations"

Now you can push the changes to your production repository:

$ git push heroku master

The production system will now use the new locale files including your latest translations!


With PhraseApp your translation workflow will get much easier:

  1. Add a new feature to your app that required translations
  2. Add the new keys to PhraseApp by uploading the locale files to PhraseApp or creating them manually within the translation center
  3. Deploy your new code to your staging environment and let your translators do their work
  4. Download the new locale files from PhraseApp and deploy them to production

Translation Center

For more information on the features available within the PhraseApp translation center please see the feature tour at

Translation Center lets you manage:

  • Locales
  • Keys
  • Translations
  • Users
  • etc.

You can get direct access to your account via the Heroku CLI:

$ heroku addons:open phrase
Opening phrase for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting PhraseApp from the add-ons menu.

Removing the add-on

PhraseApp can be removed via the CLI.

Warning: This will destroy all associated data and cannot be undone!

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

Other languages

PhraseApp supports all common localization formats, including YAML, JSON, Gettext (.po), Properties, XLIFF, Android, iOS, ResX etc. You can always access your localization files and translations from within Translation Center.


All PhraseApp support and runtime issues should be logged with Heroku Support. Any non-support related issues or product feedback is welcome at

Additional resources

Additional resources are available at: