How to Use the PhraseApp In-Context Editor

In order to make your life - and the lives of your translators - super easy, PhraseApp comes complete with a built-in In-Context editor so that your translation team can simple edit and add translations as they appear on your website, thus greatly simplifying and expediting the localization process.

One of the most powerful and useful tools that we offer is the  PhraseApp In-Context Editor.

It is super easy to use and the functionality is well worth your time.  Despite this we still receive a lot of questions about how to properly use it.

Luckily I’m here to walk you through it, step by step.

So let’s get started.

 

Installing the PhraseApp In-Context Editor

Because we love making your life easy, our editor already comes equipped with adapters for the most common web-frameworks.

And we’ll be walking you through 4 of the most common.

You can also build your own custom integration if you can’t find the framework you’re looking for below.

 

Ruby on Rails (i18n)

AngularJS

Symfony 2.X

Django

Custom Integration

 

1. Ruby on Rails (i18n)

We’ve cobbled together

 this brief video that will walk you through the steps necessary to implement our editor for your Rails-App.

 

 

The first step is going to be to add the gem like so:

Add the phraseapp-in-context-editor-ruby gem to the environment you want to use the In-Context Editor with:

Then install it using the bundle command.

 

Initialize the gem

Generate the initializer file for the In-Context Editor using the generator that ships with the gem:

 

Access Token

You can create and manage access tokens in your profile settings or via the Authorizations API.

Project-ID

You can find the ID of your project in your project settings in the Translation Center.

This will create an initializer file with some configuration options.

Activate In-Context Editor

Next you’ll want to enable the In-Context Editor in your phraseapp_in_context_editor.rb initializer file:

Add the JavaScript

Add the JavaScript snippet to your application layout within the <head> section by using thephraseapp_in_context_editor_js helper:

Done

Open your application in the browser to see the In-Context Editor applied to your app. You can sign in with any user of your PhraseApp account.

 

Turbolinks

There is a little work-around involved with making the In-Context Editor work with Turbolinks

To solve this little problem, we typically recommend disabling Turbolinks when using editor by adding thedata-no-turbolink attribute to your body tag:

Ruby on Rails Gem Configuration

You can easily enable & disable the In-Context Editor.

However, this setting is only available when you’re using the phraseapp-in-context-editor-ruby-gem.

Enabling or disabling the In-Context Editor will affect the inclusion of your JavaScript snippet when you’re using the view helper as well as the rendering of decorated key names in your views.

You can bind the flag to an environment variable:

*Please remember that the In-Context Editor is disabled by default.*

 

2. AngularJS

But before

we get into it, first you’ll need to install angular-phrase if you haven’t already done so.

If you don’t already have angular-phrase via Bower you can or download it manually by clicking this link.

Once that’s settled we’ll add the module to the AngularJS application

Add the angular-phrase module to your existing AngularJS application after loading theangular-translate module:

Configure the module:

You can find the ID of your project in your project settings in the Translation Center.

 

Add the JavaScript snippet

Add the phrase-javascript directive inside the application. This is usually best within the <head>: tag.

 

And you’re done!

Open your application in the browser again to see the In-Context Editor applied to your application.

You can now sign in with any number of users currently using your PhraseApp account.

That wasn’t so bad.

 

3. Symfony 2.X

The first thing you’re going to need to do here is to create a new environment.

We recommend creating a new environment in which the In-Context Editor will run. Let’s just call this brand new environment translation:

Start out by creating a new configuration file:

The environment should be accessible in the browser, so next lets create a front controller for it:

Extending the Base Translator

You need to override the standard translation method in order to expose the key names to the In-Context Editor:

Add the JavaScript snippet

To load the In-Context Editor, you need to add the JavaScript snippet to your layout:

Done

Start translating your app by accessing your front controller in the browser!

(The code for this step was generously provided by Malte Marx of marxbeck.)

 

4. Django

If you’re using Django

, this one’s going to be super simple to implement.

Adding the package

Of course you’ll first need to Install the django-phrase package with pip:

And add phraseto the list of installed apps:

Next, extend the template

You can now use the phrase_i18n template tag in your templates:

Note: You have to load phrase_i18n after you load ì18n in order to let django-phraseoverride the translation methods.

Add the JavaScript snippet

Add the JavaScript snippet to your base layout file. This should go inside the <head> section of your template file:

Configuration

You can configure the In-Context Editor in your settings by using these options:

And you’re done

Open your application in the browser to see the In-Context Editor applied to your application. Once again, you can sign in with any user of your PhraseApp account.

Other Frameworks

Custom Integration

 If you weren’t able to find the framework you’re currently working with, don’t despair! We’ve got instructions right here on how you can easily implement our In-Context editor manually with your own system with custom integrations.

 

Configuring the Editor

Now that you’ve finished installing the In-Context Editor on your framework it’s time to configure everything.

You’ve got several options at this point that will help you to customize things so that it works smoothly with whatever software you’re using.

 

 

Ignoring keys

This setting is likewise only available when using the ruby-gem.

Let’s say that you don’t want to include certain keys from being rendered in by the editor. If you’re working with Rails those keys could include error messages or date/time formats.

If you want to exclude these keys from being handled automatically by the phraseapp-in-context-editor-ruby gem, all you have to do is add an array of keys to your phraseapp_in_context_editor.rb initializer.

You can also use wildcards:

Keys that match one of these patterns won’t be made accessible to the In-Context Editor but will instead be rendered normally.

 

Customize key decorators

If you’re using In-Context Editor you would usually wrap the key name with “decorators” (by default they’re those curly brackets) in order to to generate unique identification keys in context with your document:

However, this can cause conflicts with other libraries such as client-side template engines like AngularJS or Ember.js) using similar syntax.

If you happen to find yourself having this problem, you may consider changing the PhraseApp In-Context Editor decorator prefix and suffix in your setup.

In order to tell the In-Context Editor which decorators the parser should be on the lookout for, all you have to do is add the following configuration values before the JavaScript snippet:

These configuration values will tell the editor to look for tags that begin with [[__ and end with __]].

For example:

If you’re using the phraseapp-in-context-editor-ruby gem to provide In-Context Editor functions, you’ll need to be sure that you have to configured your decorators there too:

If you’re not using the gem, you’ll need to make sure that you remember to adjust the key name exposure pattern in your custom code.

 

Debug mode

If for some reason you need to enable debug mode, all that is required is to add the following configuration before the JavaScript snippet:

Ajax mode

PhraseApp In-Context Editor also supports Ajax and DOM manipulation (i.e. via JavaScript) out of the box.

In order to achieve this, we use mutation observers. Keep in mind, though, that mutation observers are only supported by modern browsers.

Ajax mode can sometimes cause problems that can result in severe performance issues with the In-Context Editor. If you want to disable Ajax mode, all you have to do is add this configuration before the JavaScript snippet:

Auto lowercase

As a default setting, the In-Context Editor document parser will automatically convert all of your keys into lowercase.

If you’re experiencing issues with this behavior and would prefer to instead use case-sensitive keys with the In-Context Editor, you can disable this auto lowercase feature with this:

Force locale

If your goal is to set a specific locale when starting up the In-Context Editor you can use the forceLocalesetting to do so.

This would certainly make sense if you want to pre-select the locale that is currently displayed in your web application in the In-Context Editor as well.

Direct Links to Your Translated Content

Our context-view add-on is a plugin that makes itself available automatically once the In-Context Editor is set up and has been used recently.

The add on provides links from PhraseApp that are sent back to your application and then provides a translation.

Our context-view collects key information about which are being rendered and on which URL in your web application. It then stores this information directly on PhraseApp.

The In-Context Editor keeps track of the position of translatable content within your application.

Once set up we offer you backlinks to the In-Context Editor with the Translation Center interface, provided that you’ve added your In-Context Editor URL in your project’s settings.

 

Configure context-view

Setting up context-view is straightforward:

  1. Activate the In-Context Editor by setting up a staging environment that uses it.
  2. Add the URL to the staging environment in your project settings (In-Context Editor URL)
  3. Browse your page with the now installed editor

While you are working and browsing with the In-Context Editor, all of the information is collected automatically and will be stored, safe and sound, in PhraseApp.

 

Working with context-view

Working with context-view is super easy:

Once we have collected enough information to create a key, we will then automatically display the link to the correct URL that is next to the key in our translation view.

When the user clicks on the link he or she will be redirected to the URL of that project and taken directly to the correct page that displays the key. The browser will then automatically scroll to wherever that exact location is before the In-Context Editor will load the specified key.

You can now edit your translation immediately!

 

Make an Environment for Your Translators

In order to use our In-Context Editor you’re probably going to need to have a dedicated environment for your translators.

There are two ways that we can do this.

 

1. Use a dedicated environment

This is the method we recommend most strongly.

You can use a clone of one of your existing staging environments to create a dedicated environ for your translators.

If you decide to go with this route, the editor will always be enabled and your translators will be able to browse your website and make edits wherever they may be required.

While this may require a little bit more effort on your part in order to set up, we feel strongly that it will not only lead to a more streamlined workflow but will in general give your translators a much easier time.

 

2. Use an existing environment with a feature switch

If you really, really insist on not setting up a brand new, dedicated environment you can always use an existing one that comes equipped with an enable/disable feature.

If you’re using a Ruby gem (our favorite, can’t you tell?) it could end up looking something like this:

Note, however, that if you’re using our Ruby gem that this setting will impact the current thread. This might end up causing some strange behavior if you’re working with multiple users in the same staging environment.

Again, we really do recommend the first option, but it’s ultimately your call.

 

Conclusion

That wasn’t that bad, was it?

Our In-Context Editor is a really powerful tool that, if set up properly, will massively enhance the ability of your translators to get things done efficiently and effectively.

We hope that this quick guide will help answer some of your questions and make your life a bit simpler.

What has your experience been with the PhraseApp In-Context Editor? Let us know in the comments!

 

Looking for more information on how you can localize your software, app or website? Download your copy of our free eBook The Complete Guide to Growing Your Business with Localization here and receive tips and best practices for preparing your content for a global audience.


Also published on Medium.

Comments