Organizing and displaying content in multiple languages.

My company is moving to Confluence for all of its technical documentation, users' guides, knowledgebase, and the like.

Much of our content is available in multiple languages. English, Japanese, Traditional Chinese, Simplified Chinese, Korean, German, soon to add Portugese and Italian. You get the idea.

We're having difficulty in finding a good way to display this content in a way that keeps each language associated with others of its kind.

Currently, English is our primary language (and represents 85% of our user base). English articles are displayed, with other languages as child pages of the English page.

Unfortunately, this means that a Japanese-speaking customer doesn't have an easy path from his Japanese User Guide to the Japanese Knowledgebase.

Making this more difficult is the fact that management wants to keep the English documents available to users in all languages. Most of our work is done in English first. New KB articles and updates are always in English before they get translated. Management wants all users to have access to English docs easily.

We've had a few ideas:

1) Create a new space for each language:

  • Pros: Every document for a language is with all others of its kind.
  • Cons: Access to English documents is somewhat restricted.

2) Keep all documents in a single space. Create a parent page for each language, make all documents children of that parent page:

  • Pros: Easy access between languages, logical organization
  • Cons: Search may return duplicate entries for un-translatable English phrases/names/terms/etc. Page names can get really long (Product Name User Guide - English - v4.3) which makes lists of content look cluttered.

How do you handle your documentation in multiple languages? Using something similar to the above?

Any examples would be greatly appreciated.

3 answers

1 accepted

Hi Eric

We've had some internal discussions on this - and we came up with the following as the overriding premise:

Spaces are free - so plenty ok to have lots of them over time.

More important is navigation and search as the driving factors. Redundant search results is a deal-breaker, agree. We came up with this, for most flexibility as well as functionality:

  • separate space per doc title, per version, per translation flavor
  • maybe two letter countries in the version, and English not needed.

For example (English, French, Spanish, Chinese):

  • HibicusSoft User Guide, v1.0
  • HibicusSoft Guide de l'utilisateur, v1.0 FR
  • HibicusSoft Guía del usuario, v1.0 SP
  • HibicusSoft用户指南,v1.0 CH
  • HibicusSoft User Guide, v2.0
  • HibicusSoft Guide de l'utilisateur, v2.0 FR
  • HibicusSoft Guía del usuario, v1.0 SP
  • HibicusSoft用户指南,v1.0 CH

etc.

Also just as a note - the product name often leads in a document title and is usually not translated, regardless of language (so the docs are grouped by the products in the space list).

We felt this allowed for best of all worlds: no redundant searches, clean organization, and downstream controls on release management of the docs since easy to archive "full spaces" in Confluence (which is a good path if translation and product versioning workflow automation is enabled later).

KB Articles include a different complexity - since they can be short 1-pagers. In these cases, do you really translate each of these? If not - you could try an on-the-fly translation tool - like SpeakMyLanguage, and just retain an English as the primary source - and keep them all in one space. The KB space.

A KB has different needs and requirements than full docs - so maybe you'll want some custom functionalities for managing these, ratings, feedback, etc. All possible - just need to plan out your critical requirements, and suggest to be done somewhat iteratively as you grow and evolve this.

And what about export requirements? Will you also need PDF versions of the docs? Scroll PDF Exporter is the trick. And well worth it! It does ALOT, easily.

Other thoughts:

  • I think Atlassian organizes their doc pretty orderly - so just roll the translation flavors in with that.
  • Also - Sarah Maddox's book is a must have while you are figuring out this process - for these considerations and more, in terms of managing tech doc in Confluence. Worth every penny - Get it.
  • Zen Foundation also would be good for some instant look and feel theming, among other, that will greatly improve the user experience. Zen also provides some nice navigational macros that could help alot.

There's lots of ways to do this - but these are some simple ideas for starts.

==

I think you are not alone in this, as Confluence is used for documentation more and more in technical communications.

We'd love to talk to you about your situation if you'd be keen to reach out - ellen@appfusions.com

Ellen

I'm going to bookmark this answer. There's a lot of good info there.

I'll definitely talk to my team about SpeakMyLanguage. Translation is a big timesink.

We've dabbled (well more than dabbled - have a PoC, but not released) with an Enterprise Translations for Confluence plugin, that addresses the doc portion of the story I wrote -

But time has evaded us to get it out. Been a busy summer. Not lost in desire -

Love if you would like to be our test subject (on staging servers) - since we want to work with a customer that has LOTS of languages to play it out for real. And a clean, simple, repeatable, and reliable process built into the solution is a big part of it.

I have not a doubt in my mind that it would save your corp many many many many 1000s of $$, over and over again.

Here's another great link I found - roll-up of good write-ups, resources, etc.

https://confluence.atlassian.com/display/CONF42/Tips+of+the+Trade

Hi Guys,

Could you please recommend me a great commmercial plugin for supporting technical documentation in different languages, including English, French, and Dutch? I tried some freeware, https://marketplace.atlassian.com/plugins/ch.bitvoodoo.confluence.plugins.language, but it fails to support pagetrees and TOC in other languages.

Your advise is much appreciated!

Olha

Hi @Olha Vdovych,

have you already had a look at Scroll Translations for Confluence?

With that you can easily manage and translate multiple languages within a single space - you can translate the content, but also the pagetitles, which means the pagetree is also displaying the translated content.

Scroll Translations allows you to translate your content either directly within Confluence, but is also compatible with external Translation Management Systems.

You can export your content within a couple of clicks, import it to your TMS, translate it externally and then re-import it back to your Confluence system.

Hope that helps. If you have any further questions, please let me know.

Cheers,

Nils

Hi Nils, thank you for that answer. Do you know if a cloud version will be released soon ?

Hi Kilian,

Thanks for your interest in Scroll Translations.
There are no short-term plans to bring Scroll Translations to the Cloud, however we're tracking this requirement in our Jira system: Confluence Cloud Compatibility.

If you want you can sign up at https://k15t.jira.com/secure/Signup!default.jspa to watch, comment on or vote for this issue. We'll then send a notification for every status update.

Giving the fact that Scroll Translations supports both, manual in-Confluence translation, and has an integration with external Translation Management Systems - what would be your ideal way of translating the content? Do you have a TMS in place, or would you rather translate manually?

Cheers,
Nils

Hi Nils, 

 

Thank you for your answer !

I would say : automatic external translation first + manual corrections but I can't say it precisely until we use it.

waiting for a cloud version I use now a tab builder, Confluence macro Navitabs  https://wiki.bitvoodoo.ch/display/BVNAVITABS/Navitabs+Macros

cheers,

Kilian

Hi Kilian,

Thanks for the details. I'll make sure to let you know as soon as there are any news about a potential solution for Confluence Cloud.

Cheers,
Nils

Suggest an answer

Log in or Sign up to answer
Atlassian Community Anniversary

Happy Anniversary, Atlassian Community!

This community is celebrating its one-year anniversary and Atlassian co-founder Mike Cannon-Brookes has all the feels.

Read more
Community showcase
Sarah Goff-Dupont
Published 6 hours ago in Confluence

Think you know shares vs. @mentions in Confluence? Take this collab quiz.

To anyone who doubts that Atlassians are a little too obsessed with collaboration, and tools related thereto, let me describe a recent discussion we had (which took place on our internal Confluence, ...

66 views 2 3
Read article

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you