Lessons learned in localization Part 1: Documentation pain

Lessons learned in localization Part 1: Documentation pain

on Sep 27, 12 • by Patti Murphy • with 7 Comments

The big story for our Klocwork Insight 9.6 release was localization for our Japanese market. Prior to this effort, we provided a Japanese version that included a translation of a small portion of the documentation set. Since we’re magnanimous, we felt that others should benefit from our suffering lessons learned...

Home » General Coding » Lessons learned in localization Part 1: Documentation pain

The big story for our Klocwork Insight 9.6 release was localization for our Japanese market. Prior to this effort, we provided a Japanese version that included a translation of a small portion of the documentation set.

Since we’re magnanimous, we felt that others should benefit from our suffering lessons learned from this endeavor. Originally, I’d hoped to do a video for this entitled Crying While Localizing in homage to that fun meme Crying While Eating. But asking one’s colleagues to blubber on camera for minutes at a time while confiding their frustrations was a little too much to expect.

First up in our three-part series is one-half of our technical writing team, Kevin. Kevin came our way through a co-op placement and has settled in nicely–that is, until he was tasked with liaising and troubleshooting duties related to translation. He’s in therapy now, but he’s doing OK.

As part of his healing process, he has agreed to share some of his pain points, knowing they may help others going through the same thing. On the plus side, perhaps someone out there could provide helpful suggestions.

1. The biggest challenge – Churn and re-translation

Problem: Material often had to be re-translated when new features affected pre-existing, already-translated UI strings and documentation. With a language like Japanese where formatting and punctuation are handled differently (for example, there’s no spacing between words, except in some instances, and bold and italics are indicated with square brackets)  it was very difficult to tell where a re-translated sentence or paragraph belonged. This is what made it necessary to send entire pages out for re-translation and editing.

Solution: A freeze on development after a certain point would be helpful, but wouldn’t solve this problem entirely.

2. Help tool limitations – Page IDs and Media Wiki

Problem: We use MediaWiki for our documentation. Pages sent out for translation were exported to XML and then re-imported when translated. Any pre-existing pages had distinct page IDs. When the translated materials was re-imported, the pages were assigned new IDs. This was a problem for a number of pages that feed into context-sensitive help. New page IDs would break the local help. Old pages had to be deleted and the original Page ID had to be assigned to the translated page.

Solution: We’re  looking into it. Instituting DITA and new tools is a pricey proposition.

3. Keeping track of strings

Problem: How to maintain a master list containing all of the latest, correct translation of UI strings. Translated and implemented UI strings were reviewed by our Japanese partners for accuracy. Translations were fixed in the tool, but not updated in a master list. So when questions arose about which version of the string was used, there was no place to check for the latest version, except to troll through problem reports or email threads. Very painful.

Solution: Buckle down, do the grunt work and update that Excel spreadsheet as changes are suggested and made.

The next installments will feature lessons learned from our lead tester and one of our developers. Stay tuned.

Related Posts

7 Responses to Lessons learned in localization Part 1: Documentation pain

  1. Samuel says:

    Hi Patti and Kevin,

    Great post on the pains of localization. An easier way of doing localization might be a using a localization platform.
    Instead of manually tracking strings with a spreadsheet, it acts like a version control system for your strings.

    You would essentially use a development framework to automatically extract translatable strings from your source code into what’s called a plaintext file (e.g. .strings, .PO). That file is uploaded into the localization platform and from there, a lot of the work can be automated. For example, if you add a new string in English, it’s automatically added to the Japanese language and your translators can be notified that a new string needs to be translated. Once the translations are done you can download the plaintext file for use when you deploy your software. And everything happens in the cloud so you Translation Memory, glossary, suggestions, etc. are always accessible.

    That was a very brief overview of what we (Transifex) do. Take a look at it (transifex.com) and let me know what you think. We would love to help make localization less painful for you guys. :)

    I look forward to hearing from you.

    Samuel

  2. Kirsty says:

    You might want to consider a form of translation memory tool to capture your translations. Then, even if you *have* to get a page retranslated for a few new sentences or changes to existing sentences, at least you can reuse the existing translations easily.

  3. Kevin Welsh says:

    I appreciate the tip, Amir. We will have to take a closer look at this and see if it’s something we can use for a future release. Thanks!

  4. You can use the Translate extension with MediaWiki. Its “Page translation” feature will help you translate documentation comfortable. Link:
    https://www.mediawiki.org/wiki/Extension:Translate

  5. Helen Abbott says:

    Great post. Kevin, you know I feel your pain. Despite my love for wikis, I’m now using Help&Manual. Within a day or so I could see that translation woes would be mucho reduced-o with a tool that has permanent topic IDs independent of topic titles. The original writer here had online help integrated with the software build within a week. And not expensive.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Scroll to top