Using PhraseApp on Engine Yard
This manual explains how to use PhraseApp with a Ruby on Rails application hosted on Engine Yard.
Integrating PhraseApp into an existing application hosted on Engine Yard Cloud is easy since PhraseApp is available in the official Engine Yard Add-on store.
To enable your new translation environment the following steps are necessary:
- Prepare your application for internationalization
- Create an Engine Yard environment
- Install the PhraseApp Add-on
- Upload your existing translations
- Start translating
This manual explains how to use PhraseApp with a Ruby on Rails application hosted on Engine Yard and assumes you’re using the common YAML file based i18n backend. Other application stacks might work similar.
1. Prepare your application for internationalization
In order to use PhraseApp with your application it must be localized. That is, all translatable strings must be replaced with keys and wrapped in the t() method call.
For more information visit the i18n Rails Guide: http://guides.rubyonrails.org/i18n.html
2. Create an Engine Yard translation environment
2.1 Add a new application
Unless the application you want to translate with PhraseApp is configured in your Engine Yard account, you will need to create it first:
Log in to your Engine Yard panel and click “Add an Application”:
Enter the details of your application, such as the name, the location of its repository and its Rails version. In this example we use a Demo Todo application:
Add the application to your Engine Yard account by clicking “Create Application”.
2.2 Start a new Engine Yard environment
The PhraseApp translation solution is meant to run on a separate
translation environment or in
development but never in your
Thus you should start a separate environment for your Engine Yard application. In this example we use the
staging Rails environment but any other will work as well.
To create a new environment, go to your application in your Engine Yard control panel and click “Create New Environment”. In case you just created the application you should already see the form to create the environment.
Give your new environment a name (e.g. “Translation”) and select
staging as the Rails environment or use a custom one (e.g.
translation). Fill out the technical details about your new environment according to the setup you prefer and create the environment by clicking the “Create Environment” button on the bottom of the page.
3. Install the PhraseApp Add-on
3.1 Activate the Add-on
After your staging environment is configured you should activate the PhraseApp add-on for the new environment. Visit the Add-on store for the environment by clicking “New Add-on” on the bottom of your environment configuration page:
Choose the “PhraseApp” add-on and sign up for the service by clicking “Set it up”.
Next, activate it for the appropriate environments. This will create an
project_id variable that can then be used in your app.
You can find your access token and project id on the bottom of your Engine Yard application environment settings page in the “Add-on” section.
Learn more about managing Add-ons in the official Engine Yard documentation
3.2 Add the phraseapp-in-context-editor-ruby gem
Next, add the
phraseapp-in-context-editor-ruby gem to your Rails application by adding it to your Gemfile:
group :staging do gem 'phraseapp-in-context-editor-ruby' end
and install it via Bundler:
$ bundle install
3.3 Initialize the phraseapp-in-context-editor-ruby gem
Use the Rails generator task to initialize the gem for your Rails app:
$ bundle exec rails generate phraseapp_in_context_editor:install --access-token=YOUR_PHRASEAPP_ACCESS_TOKEN --project-id=YOUR_PHRASEAPP_PROJECT_ID
Remember: You can find your access token and project id on your application environment settings page.
phraseapp_in_context_editor.rb initializer file in
config/initializers and replace the access token and project id with a more flexible call to the env setting provided by the Engine Yard addon:
PhraseApp::InContextEditor.configure do |config| ... config.enabled = (ENV['RACK_ENV'] == 'staging') config.access_token = EY::Config.get(:phraseapp, "access_token") config.project_id = EY::Config.get(:phraseapp, "project_id") ... end
<head> ... <%%= phraseapp_in_context_editor_js %> ... </head>
4 Upload your existing translations
Besides managing your projects and locale files through the web interface you can also use the PhraseApp Command Line Client. Follow the install and configuration instructions and use the client to push your locales:
$ phraseapp push
5. Start translating
5.1 Deploy your app
Once everthing is set up you can deploy your application to the new translation/staging environment. After that, just visit your application in the browser. You should now see the PhraseApp login window of the In-Context-Editor.
5.2 Create the first translator user
To create the first user to work with your new translation environment simply sign in with the “View Dashboard” link within your Engine Yard config panel for the PhraseApp add-on. This link will sign you into your PhraseApp account where you can manage your projects, translations and users.
After signing in, visit the user management section. Create your first (actually second) user manually by clicking “Invite user”. Make it a manager user, that is a user with access to all of your projects. The user will instantly receive an invitation link via email.
You can use these user credentials now to log into PhraseApp Translation Center and into your In-Context-Editor installation on your translation environment.
5.3 Translate your app
With your new In-Context-Editor in place and your first translator user created, you can now start translating your app. You will soon notice how easy it is to edit translations on your site and how the quality of your translations will improve with the context information that is now available through the editor.
Congratulations on a new and improved translation experience with PhraseApp and Engine Yard!
5.4 Deploy your new translations
Once you have done all the translation work you will most likely want to ship your new translations to your production environment:
- Download your updated locale files from PhraseApp with the PhraseApp Command Line Client:
$ phraseapp pull
- Run the tests for your app (if available)
- Commit the new/updated files to your repository
- Deploy the new revision of your app to your Engine Yard production environment