Translating Forms using XLIFF

Many of you have been translating your forms using XLIFF and XSLT to export/import various strings found in the form.  If you haven’t, there’s a nice description of the process here:

Translation Workflow

  1. Configure Designer to generate resource id values for strings in the template
  2. Use XSLT to extract resources from the template (xdp) into XLIFF format
  3. Use an XLIFF- based translator to generate translated strings
  4. Review/approve the translations
  5. Use XSLT to update the template (xdp) with the translated strings

Step 1 has been made easier in the ES2 designer. You can do it from the options menu:


For reference, the XLIFF 1.1 schema is described here:

And the XSD definition can be found here:

The using_xliff.pdf document has two xslt scripts attached.  I was having some trouble with the version that extracted the strings, and made a fix. Here are my changes to XDPtoS2X.XSLT.

A Translation Form

Today’s translator.pdf sample form is bound to the XLIFF 1.1 schema.  This means it can be populated with the XLIFF data extracted in step 2 (here is the XLIFF data we’re using in this sample).  Steps 3 and 4 above can now be executed using this form. This has a couple of immediate benefits over other translation tools:

  1. Your XLIFF editing tool (Adobe Reader) is free.  You can use Reader as long as you set up the form so that the XLIFF data gets injected in another process and add a submit button to send back the updated data. If you need to manage the data from the client then you need to either use Acrobat or a rights-enabled translator form.
  2. Any rich text found in the XLIFF data can be reliably edited in Reader — since Reader understands the XHTML subset supported by XFA.

Some things you will notice when you look at XLIFF data in the form:

  • The header area allows you to specify the various translation phases: design, translate, review.  This will allow you to adapt the form to be part of a translation workflow where the roles of translation and approval may be performed by different individuals.  When in the review phase, the form enables an approval checkbox for each translation.
  • Workflow participants can attach notes to each phase and to each individual translation. 
  • The data to be translated is either plain text or rich text (XHTML).  Each translation includes an indication regarding the text content type.  When editing rich text use control+e to bring up the rich text editing toolbar.
  • There is a copy button that copies the source text to the target text — when that’s convenient for the translator.


Notice that the translator form has a preview button at the top.  Preview will allow the translator to interact with the document that is being translated — and provide a much richer translation experience.  The preview button click event will look for other open PDFs on your machine, and if it finds one that matches the translation strings currently being edited, then preview will be enabled.  Note that by default open PDFs are not visible to each other.  We make the preview PDF visible by adding this script:

form1::docReady – (JavaScript, client) = true;

When a document is disclosed, it is fully accessible to any other document. 

Try opening the translator form and the preview form: po.pdf side by side.  Click the preview button.  Now all kinds of good things happen:

  • When you enter into a subform that does a translation, the corresponding field in the preview form gets highlighted (where possible) and the preview document scrolls to the field in question.
  • We add context information to the translation — some indication of where the text comes from.
  • Each translation inherits the ambient font and paragraph properties of the text being translated. 
  • When a translation is specified, the preview document gets updated with the translated string. (Note that this merely changes the runtime representation of the form — it has not updated the actual form definition: the template).
  • When a translation changes a caption or text object, the translator form allows you to change the size, caption reserve and position of the translated object.

Note that if you interact with the preview form and change the layout (add/remove subforms) you will need to click the preview button again in order to refresh the cached data in the translator form.

Exercises left to the user

From what I’ve provided here, you will have an XLIFF editor, but I haven’t given you enough to construct the whole workflow.  Here are some of the issues you need to tackle:

  • Dynamic forms are variable, and that means that not all elements in the template appear in the preview form.  For example, a form could be designed so that either subform A or subform B is visible.  That means you may want to preview the form twice with data that creates both permutations.
  • The current XSLT scripts handle only strings.  The XSLT script that updates the XDP doesn’t apply updates to coordinates.
  • This form really ought to be incorporated into a LiveCycle workflow with separate steps for the translator and reviewer.  Use the LiveCycle XSLT component to apply the translation.
  • The current mechanism of opening the forms side-by-side is a bit awkward.  It would be nice if they could be hosted in a container application.  Maybe a web page. Maybe an AIR application.

More about Disclosed

You shouldn’t turn on disclosed for production forms.  They should be disclosed only while being translated.  Having them disclosed means that they are vulnerable to untrusted PDFs.  i.e. their behaviour could be changed by another rogue PDF that you might have opened.

There is an alternative to using the disclosed property.  You could install folder-level JavaScript on the system of your translator.  Folder level JavaScript executes in privileged mode and can
find all open documents whether disclosed or not.

Check Sample Version

The translator form uses a script object to return coordinates of form objects.  I’ve shared it as a fragment here.  As with previous samples, I’ve included logic so that you can check whether there are updates to the form or its embedded fragments.  This check performs an http get operation on an inventory file hosted on my blog site.  In the recent Reader releases, this http get operation is subject to tighter security.  When this function executes the first time, a yellow warning bar will appear in Reader/Acrobat and the http get request will fail.  In order to check version, you will need to choose to trust this PDF and then click the button again.

The Deep End

Storing coordinates:

As mentioned, the translator form allows you to modify the coordinates and dimensions of an object.  The way this is stored in the schema is with the coord attribute:

<group restype="description">
  <trans-unit id="034C9948-DAAC-4544-B7C7-F71791D37105"
     <xlf:target xmlns:xlf="urn:oasis:names:tc:xliff:document:1.1"

According to the XLIFF schema, the coord attribute is used to store x;y;w;h.  I took the liberty of adding a fifth number: caption reserve.   My apologies for not (yet) providing an xslt script to apply the changes to coordinates — maybe one of the readers of this blog will offer the solution.

7 Responses to Translating Forms using XLIFF

  1. miquel golobart says:

    It seems some links are broken (XDPtoS2X.xslt and po_strings.xml). Can you fix them?

    • John Brinkman says:

      I suspect these are issues related to having our blog infrastruture moved to WordPress.
      Oddly, when I try to download those files using firefox it works ok, but fails when using IE.
      I’ll see if I can get it fixed.

      Meanwhile, as far as the XSLT scripts go, note that these are now included in the Designer installation. You should use the scripts from there.

      good luck,


  2. miquel golobart says:

    if i’m not wrong, firefox doesn’t work either, it seems like you can save the link, but you just get an html page.
    Thanks for your suggestion on use scripts from Designer installation.

  3. miquel golobart says:

    Yes, now it works.

  4. Steven Dayton says:

    I’m just not getting this process understood. You say in the article that Adobe Reader is used as the XLIFF editing tool. How?

  5. John Brinkman says:

    Using Adobe Designer you can create a PDF Form where the form data is saved as XML — according to a specified XML Schema. The sample in this blog is a form that edits data according to the XLIFF schema. It doesn’t handle the full XLIFF schema — just those parts that are used by strings extracted from form designs.
    Adobe Reader isn’t enough to implement the full solution, since it has no way to import/export the XML (XLIFF) data. You need either Acrobat or you need a (LiveCycle) server to manage the data for you.