Migrate from Tolk to Phrase

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.

Phrase

Phrase 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 Phrase

If you have decided to give Phrase 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 Phrase, 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 the command line tool and initialize your Phrase 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 Phrase 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 Phrase 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 Phrase

There are quite some differences between Tolk and Phrase:

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

Further reading

• Tolk on Github
• Phrase Command Line Client