Integrate In-Context-Editor into any web framework

This article covers the integration of the In-Context Editor into a custom web framework or a technology that is not yet covered by one of the many adapters we already offer.

General information

PhraseApp works great without the In-Context Editor but it gives you even more powerful tools for your localization workflow so we recommend to use In-Context Editor whenever possible.

Prerequisites

In order to use In-Context Editor your application must be:

  1. A web-based application: Websites, web applications, Mobile Sites etc.
  2. Have access to the web: We recommend to use In-Context Editor on a web server that can be accessed by all of your translators but you can run it in your local network or your local machine as well if you don’t want to set up a separate environment for it.
  3. Prepared with a key-value based localization file structure: In-Context Editor only works for web sites that already have translatable strings extracted and a view layer that uses a key-value structure to render translations.

Concept

The integration of In-Context Editor basically comes down to two easy steps:

  1. Expose the names of your keys to the view/template layer
  2. Include a small JavaScript snippet that renders the editor

See the sections below for a detailed explanation.

Exposing key names

Typically a view layer renders translations by passing the name (key) of a translatable string to some sort of translation method/view helper. See the following (simple) PHP code example to see how most helper methods look like:

$translations = array(
  "page.headline" => "Some Headline",
  "page.link.label" => "I am a link",
  "page.link.hint" => "Click me"
)

function translate($keyName)
  return $translations[$keyName];
end

In your template you typically would then render the output of the translate() method instead of the actual translated string:

<h1><?php echo translate("page.headline"); ?></h1>

PhraseApp needs to know for which key it should render translations in your template. Thus you need to expose the name of your key instead of the translation. The key has to be rendered in the following format in order to be recognized by PhraseApp:

{{__phrase_NameOfYourKey__}}

So if you would have used the key page.headline in your template you should now instead render the string {{__phrase_page.headline__}}.

The easiest way to accomplish this is to modify your translate() helper method in a way that it exposes the key name in the required format when needed, e.g.:

function translate($keyName)
  if ($phraseModeEnabled) {
    return "{{__phrase_".$keyName."__}}";
  } else {
    return $translations[$keyName];
  }
end

Depending on the framework you use, you can override the translation helpers in your code or create a wrapped version of it that you can then use in your templates. If you need any assistance, please contact the PhraseApp support.

Also, feel free to look at the HTML source code of the demo application in order to understand how key names should be exposed in your setup.

Escaping of Key Names / Special characters

Please make sure that you convert the key name to a format that is readable by the PhraseApp parser. See the following list of chars that need to be escaped when exposed to the In-Context Editor:

Char Escaping Example
< [[[[[[html_open]]]]]] {{__phrase__<key__}} becomes {{__phrase__[[[[[[html_open]]]]]]key__}}
> [[[[[[html_close]]]]]] {{__phrase__key>__}} becomes {{__phrase__key[[[[[[html_close]]]]]]__}}

Note that the In-Context Editor will unescape these chars for you later in the process. So the actual key names will not change but must only be escaped in your markup in order to parse them correctly.

If the In-Context Editor parser should have trouble with other special chars, please contact us.

JavaScript Snippet

Besides exposing the keys, you need to include the In-Context Editor itself. It is basically a JavaScript snippet that includes all the code that is required to:

  • Communicate with the PhraseApp API
  • Render the user interface
  • Provide login
  • and much more

Simply include the JavaScript snippet in your application layout and make sure to provide the correct project ID. You can find the ID of your project in your project settings in Translation Center.

<script>
    window.PHRASEAPP_CONFIG = {
      projectId: 'YOUR_PROJECT_ID'
    };
    (function() {
        var phraseapp = document.createElement('script'); phraseapp.type = 'text/javascript'; phraseapp.async = true;
        phraseapp.src = ['https://', 'phraseapp.com/assets/in-context-editor/2.0/app.js?', new Date().getTime()].join('');
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(phraseapp, s);
    })();
</script>

There are several configuration parameters as well but usually you should be fine with the default settings.