Migrate from tolk to PhraseApp

tolk is an open source gem originally developed by David Heinemeier Hansson that provides an engine to manage YAML based translations for Rails applications.

While tolk is a good solution to get rid of the manual editing of the YAML files, it is very very limited in its features. What tolk does not provide:

  • tolk has no multi-user management
  • tolk only supports YAML based locale files
  • tolk does not support verification workflows or advanced stats on translation progress
  • tolk does not provide commenting or tagging
  • tolk does not provide versioning for translations

Usually its users learn quite fast that they need a more advanced solution to manage their translation workflow.



PhraseApp is an advanced translation management platform. It offers a lot of features that you will not find in tolk:

  • Multi-Format support (e.g. for YAML, Gettext, XLIFF, iOS Strings, Android XML and many more)
  • Commenting, Tagging and a fast and flexible search
  • API
  • The powerful In-Context Editor
  • Multi-User support with customizable privileges
  • Screenshot upload and description annotations for keys
  • A complete history of all translations so you can revert translations easily

Migrating from tolk to PhraseApp


If you have decided to give PhraseApp as an alternative to tolk a try, we are happy to support you with our migration guide. Migrating is pretty easy:

1. Sync your translations once again


Since you most likely want to use your latest translations with PhraseApp, you will first need to sync your translations with tolk:

$ rake tolk:dump_all

This will dump the latest version of your translations from tolk into your Rails locale folder (typically in ./config/locales)

2. Sign up and create a project


If you haven’t done already, you should create your free trial account and use our Getting Started Wizard to create your first project.

3. Install the command line client


Download thecommand line tool and initialize your PhraseApp project:

$ phraseapp init

This will create a .phraseapp.yml config file in your project.

4. Uploading locale files


The equivalent to the tolk:import rake task is the push command:

$ phraseapp push

After uploading all locales, they are available within your PhraseApp Translation Center.

5. Downloading locale files


After you have translated all of the strings in a new locale or updated some text, you will probably want to download them in order to deploy them to your production system. This can be done with the pull command:

$ phraseapp pull

You can now add the new localization files to your source control and deploy them to production.

6. Advanced use


Explaining all of the advanced features of PhraseApp would certainly go beyond the scope of this guide. We strongly recommend our guides to learn all about the powerful features and how you can use them with your translation workflow.

7. Cleanup


Now you can remove tolk from your application. We encourage you to backup all files and - especially - the tolk database tables. To remove tolk, just:

  • Drop the database tables (usually beginning with tolk_*)
  • Remove the gem and the initializer from your app

Major differences between tolk and PhraseApp


There are quite some differences between tolk and PhraseApp:

tolk PhraseApp
Installation Install gem, create tables, import locales phraseapp init You do not need to change your application in order to use PhraseApp. No third-party dependencies!
Upload locale files rake tolk:import phraseapp push PhraseApp does not override existing translations and will not attempt to perform any merges
Download locale files rake tolk:dump_all phraseapp pull

If you need any further support to perform the migration, contact us.

Further reading