1. Help Center
  2. Phrase for Developers
  3. Installing and setting up the Phrase In-Context Editor (ICE)

Setting up the In-Context Editor for a more efficient translation process

The In-Context Editor is designed to help translators get things done more efficiently. After installing the In-Context Editor, you can customize it and make it work seamlessly with your technology.

The In-Context Editor is available when you choose the Pro plan or a higher plan.

Enabling and disabling the In-Context Editor

This setting is only available when using the phraseapp-in-context-editor-ruby gem.

You can enable or disable the In-Context Editor explicitly. This will affect the inclusion of the JavaScript snippet (when using the view helper) and the rendering of the decorated key names in your views:

PhraseApp::InContextEditor.enabled = true|false

For example, you can bind the flag to an environment variable:

PhraseApp::InContextEditor.enabled = (ENV["IN_CONTEXT_EDITING"] == "1")

Note that the In-Context Editor is disabled by default.

Ignored keys

This setting is only available when using the phraseapp-in-context-editor-ruby gem.

You can exclude keys from being rendered with the In-Context Editor. When working with Rails, you might choose to ignore keys for things like error messages or date and time format keys. To exclude these keys from being handled automatically by the phraseapp-in-context-editor-ruby gem, add an array of the keys to your phraseapp_in_context_editor.rb initialization file. You can use wildcards as well:

PhraseApp::InContextEditor.configure do |config|

  config.ignored_keys = ["date.*", "forbidden.key",   "errors.messages*"]

end

Keys matching any of these patterns will not be made accessible to the In-Context Editor. Instead, they will be rendered normally.

Customize key decorators

When using the In-Context Editor, you’ll typically wrap key names with decorators (curly braces, by default) to generate unique identification keys within the context of your document:

{{__phrase_YOUR.KEY__}} 

However, this can cause conflicts with other libraries (e.g., client-side template engines, including AngularJS and Ember.js) that use a similar syntax. If you encounter this problem, you might want to change the In-Context Editor’s decorator prefix and suffix in your setup. To tell the In-Context Editor which decorators the parser should look for, add the following configuration values before the JavaScript snippet:

window.PHRASEAPP_CONFIG = {

  prefix: '[[__',

  suffix: "__]]"

}

This will tell the editor to look for tags beginning with [[__ and ending with __]], like this:

[[__phrase_YOUR.KEY__]]

If you’re using the phraseapp-in-context-editor-ruby gem to provide In-Context Editor functionality, make sure to configure decorators there, too:

PhraseApp::InContextEditor.configure do |config|

  config.prefix = "[[__"

  config.suffix = "__]]"

end

If you aren’t using the gem, make sure to adjust the key name exposure pattern in your custom code accordingly.

Debug mode

To enable debug mode, add the following configuration value before the JavaScript snippet:

window.PHRASEAPP_CONFIG = {

  debugMode: true

}

Ajax mode

The In-Context Editor supports Ajax and DOM manipulation (i.e., via JavaScript) out of the box. To achieve this, it uses mutation observers. However, these are only supported by modern browsers.

Ajax mode can cause problems in some cases, and it may result in severe performance issues when using the In-Context Editor. To disable Ajax mode, add the following configuration value before the JavaScript snippet:

window.PHRASEAPP_CONFIG = {

  ajaxObserver: false

}

Automatic case conversion

By default, the In-Context Editor’s document parser converts all keys to lowercase. If you’re experiencing issues with this behavior and want to use case-sensitive keys within the In-Context Editor, consider disabling the automatic lowercase feature:

window.PHRASEAPP_CONFIG = {

  autoLowercase: false

}

Forcing a locale

To set a specific locale explicitly when starting the In-Context Editor, you can use the forceLocale setting. This is useful if you want to preselect the locale currently displayed in your web application in the In-Context Editor as well.

window.PHRASEAPP_CONFIG = {

  forceLocale: "pt-BR"

}

Full reparsing

Enable fullReparse if you’re using the In-Context Editor with a JavaScript framework that uses Virtual DOM, such as React. This allows proper reparsing when DOM changes are detected.

window.PHRASEAPP_CONFIG = {

  fullReparse: true

}

Branching

If you use our Branching feature and want to initialize the In-Context Editor on a different branch in your project, add the following configuration value before the JavaScript snippet:

window.PHRASEAPP_CONFIG = {

  branch: [insert_branch_name]

}

Single sign-on

If you use our single sign-on feature and want to initialize the In-Context Editor with SSO enabled, add the following configuration value before the JavaScript snippet:

window.PHRASEAPP_CONFIG = {

  sso: {

    enabled: true,

    identifier: [insert_company_identifier]

  }

}

To require users to sign on using SSO, you can set the enforced parameter:

window.PHRASEAPP_CONFIG = {

  sso: {

    enforced: true

  }

}