Translating documentation developed on Confluence wiki

A few people have asked me recently about translating content into other languages, and what functionality Confluence provides to help that process. This post is a summary of what I know, in the hope that it will give people pointers to follow up on. It’s also an invitation to share what you know about translating technical documentation.

We don’t translate our own documentation yet, so this post is based on conversations with people who need to translate their documentation, on my subsequent investigations, and on a couple of presentations I’ve attended. The presentations focused on content translation in general, and had nothing to do with Confluence.

If you’d like to add information about the requirements and process of getting documentation translated, please comment on this post. I’d love to know more about this area of technical writing.

Getting the documentation to a translation company

Translation companies need the documentation in a specific format. For example, some companies work with Microsoft Word, others with XML. So you’ll need to find out what formats work best for them, and then check if you can convert your Confluence content to that format.

Using core Confluence (that is, without adding any plugins) you can export your content to

  • A proprietary XML format – useful for backing up your content and for transferring content from one Confluence site to another.
  • PDF.
  • HTML.
  • Microsoft Word –a basic single-page conversion done via HTML and CSS.

The Confluence documentation has the details.

Plugins provide additional export formats:

Getting translated content back into Confluence

You may want to provide the translated content on a Confluence site, as well as the original-language content. In some scenarios, you may want to do the following:

  1. Send the initial English content for translation. (Let’s assume the original language is English.)
  2. Upload the translated content into a Confluence space.
  3. Update the English content for the next product release.
  4. Send the updated English content for translation.
  5. Also include a copy of the current version of the translated content, for updating by the translators.
  6. Load the new version of the translated content into Confluence.

Looking at steps 1 and 2: When sending the English content to the translators, it would be best to send the Confluence XML, so that you can retain the formatting and macros that are part of your content. Then you can upload the translated content into Confluence without having to reapply the formatting and macros.

Looking at steps 5 and 6:  If you need to put the new version of the translated content back into Confluence, then the only available option is to use Confluence’s proprietary XML format. These are the steps to follow:

  • Export the current version of the translated content from Confluence to XML.
  • Send it to the translators and ask them to update the content embedded in the XML.
  • Import the updated XML back into the wiki.

Getting rid of page history in the Confluence XML export

The problem with the current XML export is that it includes all the page history, so it is difficult to isolate the current content from the previous versions of the pages. This is troublesome when you are sending your original-language content to the translation company, because the content will probably have been through multiple reviews and releases. Each page will therefore have many versions.

There are two rays of hope here:

  • One of the awesome Confluence developers is working on an update which will allow you to exclude page history when doing the XML export. I don’t know yet when this feature will be available, although I have promised him chocolate if he gets it into a release soon. 🙂
  • A suggestion: You can use the Copy Space plugin to copy your content to a different space. This will exclude all page history. Then you can do the XML export from the new space. Note that the space key will be different too.

Optimising your content for translation

Here are a couple of references about optimising your content for tranlsation. They discuss content in general, not specifically Confluence-based content .

Content reuse

One aspect of optimising your content is to employ content reuse. This helps to ensure consistency of terminology, which makes translation easier and the results more reliable. Content reuse can also reduce the number of words to be translated, thus reducing translation costs. In Confluence, you can use the include and the excerpt include macros to reuse content across pages. I’ve written a few posts about content reuse which may be useful.

Any more?

Over to you. 🙂

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 5 February 2012, in Confluence, technical writing, wiki and tagged , , , , , . Bookmark the permalink. 6 Comments.

  1. The best source out there on writing for translation is The Global English Style Guide by John R. Kohl, a linguistic engineer at SAS.

  2. Something I tried some time ago is setting up an internationalised space in confluence. The task was to host a german and an english version of help text in a space and present it according to language setting in the browser or the users profile in confluence.
    Performing the translation itself was not that complicated. The source was german and I duplicated all pages using the Bob Swift’s command line interface in a separate page tree appending “_en_todo” to the page name.
    Translation was done online in this space removing the “_todo” after the translation was finished.

    The really complicated part was finding a process to keep the english versions updated. Our dev’s write help texts in german and a technical writer team would have to filter changed pages and update the english version correnspondingly.

    The project was stopped preventing me from getting any further on this, but my message is merely translating documention is only half the job. Keeping it in sync over all translations is the challenging part.

  3. You may also want to check out our Language Plugin (non-commercial), that lets you have the same content in different languages on the same Confluence page:

    • Hallo Remo
      Wow, that plugin looks awesome. I see that it’s compatible with Confluence 4.x already, and has had more than 1300 downloads. Congrats! Have you had much feedback from people using it?
      Cheers, Sarah

      • We received lots of great feedback so far, most of them in the comments section on our website. Some good feature request are already implemented now, like reverting to the Confluence default language if no macro for the current users language exists, or adding support for browser language detection.

        But there were also some feature request, we were not able to implement, like adding support for anonymous users, or overwriting the page title in more locations like pagetree, breadcrumbs, etc.

  4. Hallo all

    Thanks so much for your comments! This interesting link came in from rick sapir via Google+. It’s a wiki for discussion of the impact of wikis on translation:

    Cheers, Sarah

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: