PhraseApp - Translate Software Better

This add-on is operated by Dynport GmbH

Edit and share locale files online. In-context copywriting and translation.

PhraseApp - Translate Software Better

Last Updated: 07 May 2015

Table of Contents

PhraseApp is a online editor for all common language file and locale formats including YAML, JSON, Gettext (.po), Properties, XLIFF, Android, iOS, ResX etc. You can always access your locale files and translations from within our online Translation Center.


With PhraseApp your translation workflow will get much easier:

  1. Add a new feature to your app that requires translations
  2. Push new keys to PhraseApp or create them manually within our Translation Center
  3. Deploy your new code to your staging environment and let your copywriters and translators change finalize the content and translations
  4. Pull the updated locale files from PhraseApp and deploy changed translations to production

In-Context Editing

PhraseApp comes with an In-Context Editor for Rails, AngularJS, Django and Symfony. You can edit your copy or translations directly on your site without having to deal with localization files at all.

Your copywriters and translators will see the context of a certain text. While changing it they can immediately see if the length of the text fits in the given space or what the intention of a certain piece of text is.

Free your developers from having to deal with the content and structure of localization files by automating translation workflow with our API.

A sample Sinatra application is available at Github

Provisioning the add-on

PhraseApp can be attached to a Heroku application via the heroku command:

$ heroku addons:create 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 Rails or Ruby in general

Adding the gem and importing locale files

Add the phrase gem to your staging and development environment:

group :development, :staging do
  gem 'phrase'

and install the gem with the bundle command:

$ bundle install

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 your locale files to the PhraseApp Translation Center:

$ bundle exec phrase push ./config/locales/

PhraseApp now knows about your locales and the keys in your application.

Pulling locale file changes

Whenever you want to deploy changed translations from our Translation Center you need to pull the locale files back to your repository, just as you would with git for changes made by other developers.

$ bundle exec phrase pull

PhraseApp automatically stores pulled translations in a different folder than your development locale files, phrase/locales. We advice to use a different locale folder for production to not overwrite any local changes accidentally. 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]

In-Context Editor

The In-Context Editor can for example be integrated in a staging environment for copywriters and translators. It is not recommended to include the PhraseApp In-Context Editor in your production environment because it is a authoring tool for your content and translation.

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.

Initialize PhraseApp

To automatically load the In-Context Editor with your application you need to add the following two lines to your staging initializer (Rails):

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

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

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

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);

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 a feature or content of your application, 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!

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 / Language Files
  • 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:destroy phrase
-----> Removing phrase from sharp-mountain-4005... done, v20 (free)


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: