Getting Documentation Ready for Localization - The Audience Speaks

Don't you love it when the audience is listening? Even more when they write back?

Last week's post included a handful of considerations about preparing documentation for localization. An alert reader and industry veteran (who prefers obscurity to the onslaught of Web-fame that this post will undoubtedly unleash) sent me a table of resources she has compiled on the topic over several years' time:

Title	Publisher	Summary and Notes
25 Tactics to “Internationalize” your English	Intercom (STC magazine)	Hints on writing localization-friendly copy. (One example: choose words with one or few meanings).
Authoring and controlled language	TAUS (Translation Automation User Society)	A guide to how and why companies are starting to manage their writing and editing “upstream.”
Basic Tips for Loc Writing	Globalvision International	A brief overview from a translator’s perspective on how to simplify the work of the translator.
Color Connotations	Lionbridge	Guidelines on how different colors are perceived throughout the world.
Localizing Art	Globalvision International	Tips on how to improve graphics localization.
Reducing Localization Costs	Globalvision International	Tips on how to write text that is less expensive to localization – both new copy and updates.
Tech Writing for Localization	Client Side News Magazine – Tech Writer supplement	How culture and jargon impacts writing and localization. Tips on the purpose and benefits of standards and templates.
Terminology Management White Paper	Jonckers	Why consistent terminology is important to localization.
Writing for Translation	Multilingual Magazine	Tips on how to simplify text. Information on how DITA impacts localization.

The contributor comments, "Please note that some of this is proprietary to the publisher and not generally available."

Find what you can and help yourself!

Getting your Documentation Ready for Localization

Have you had to prepare your documentation for localization yet? My experience is that in almost all companies, writers have far too many other oppressive concerns gnawing at them to think about writing for localization.

A few days ago an industry colleague sent me a message asking, "Do you have experience making recommendations for how documentation can be authored for localization? I am looking to make our doc  process more efficient to reduce costs."

I replied that, given his stature and tenure in the industry, there was not likely anything I could suggest that he hadn't already considered. Nevertheless, I sent him a list of ideas, in increasing order of difficulty:

1. Make sure all the writers' computers are plugged in. (A bit of ironic humor I could not resist.)
2. Is it easy to get from the authoring tool(s) into TM, and back out into publishable format? This is my current headache with an API reference manual we localize for one client, because moving from source language to the translator tools and back to target format is a colossal headache. If you have similar problems, devote some cycles at the format-layer, even if it means writing an interface between your content management system and the translation tool.
3. There are "authoring memory" tools that can suggest and re-use already-xlated source text, so that writers don't say nearly the same thing multiple times and incur unnecessary TM penalties. Sajan has one, and SDLX contains one as well. I've never used either one, but I can imagine that success with the tools would require somebody with the documentation-familiarity of a technical writer and the global consciousness of a localization manager. Like you.
4. I've presented on localization to a variety of audiences, and have consistently found tech writers to be the most interested in it, vastly more so than developers. When you show writers how the TM tools work, tell them how they can save money and re-use content, and let them know that you care about the impact of their work on international products, they will smell the coffee and engage. This takes a bit of evangelism, but it's worth it if the writers change their own practices.
5. Convert everything to XML. Although Renato and Don of Common Sense Advisory joke that that will fix any L10n problem, it's nonetheless a good, long-term direction in which to move. It's easier to re-use text, and easier to mark text that should/should not be translated. That will save you money.
6. Start a program of controlled language authoring (dumbing down the sentences, always writing in a structure that machine translation will recognize, etc.). I guess that GM and Caterpillar are poster children for this kind of thing, but it puts the writers (and you, in the bargain) through the change of life, which is why I mention it last.

What about you? Have you faced this in your organization? How have you made document localization easier for the company, without driving your writers crazy?

If you liked this post, have a look at Getting Writers to Care about Localized Documents.

Localizing Robohelp Files - The Basics

We get a lot of search engine queries like "localize Robohelp file" and "translate help project." I'm pretty sure that most of them come from technical writers who have used Robohelp to create help projects (Compiled HTML Help Format), and who have suddenly received the assignment to get the projects localized.

The short answer
Find a localization company who can demonstrate to your satisfaction that it has done this before, and hand off the entire English version of your project - .hpj, .hhc, .hhk, .htm/.html and, of course, the .chm. Then go back to your regularly scheduled crisis. You should give the final version a quick smoke test before releasing it, for your own edification as well as to see whether anything is conspicuously missing or wrong.

The medium answer
Maybe you don't have the inclination or budget to have this done professionally, and you want to localize the CHM in house. Or perhaps you're the in-country partner of a company whose product needs localizing, and you've convinced yourself that it cannot be that much harder than translating a text file, so why not try it?

You're partially right: it's not impossible. In fact, it's even possible to decompile all of the HTML pages out of the binary CHM and start work from there. But your best bet is to obtain the entire help project mentioned above and then use translation memory software to simplify the process. Once you've finished translating, you'll need to compile the localized CHM using Robohelp or another help-authoring product (even hhc.exe).

The long answer
This is the medium answer with a bit more detail and several warnings.

• There may be a way to translate inside the compiled help file, but I wouldn't trust it. Fundamentally, it's necessary to translate all of the HTML pages, then recompile the CHM; thus, it requires translation talent and some light engineering talent. If you don't have either one, then stop and go back to The Short Answer.
  
• hhc.exe is the Microsoft HTML Help compiler that comes with Windows. It's part of the HTML Help Workshop freely available from Microsoft. This workshop is not an authoring environment like Robohelp, but it offers the engineering muscle to create a CHM once you have created all of the HTML content. If you have to localize a CHM without recourse to the original project, you can use hhc.exe to decompile all of the HTML pages out of the CHM.
• Robohelp combines an authoring environment for creating the HTML pages and the hooks to the HTML Help compiler. As such, it is the one-stop shopping solution for creating a CHM. However, it is known to introduce formatting and features that confuse the standard compiler, such that some Robohelp projects need to be compiled in Robohelp.
• Robohelp was developed by BlueSky Software, which morphed into eHelp, which was acquired by Macromedia, which Adobe bought. Along the way it made some decisions about Asian languages that resulted in the need to compile Asian language projects with the Asian language version of Robohelp. This non-international approach was complicated by the fact that not all English versions of Robohelp were available for Asian languages. Perhaps Adobe has dealt with this by now, but if you're still authoring in early versions, be prepared for your localization vendor to tell you that it needs to use an even earlier Asian- language version.
• Because the hierarchical table of contents is not HTML, you may find that you need to assign to it a different encoding from that of the HTML pages for everything to show up properly in the localized CHM, especially in double-byte languages.
• The main value in a CHM lies in the links from one page to another. In a complex project, these links can get quite long. Translators should stay away from them, and the best way to accomplish that is with translation memory software such as Déjà Vu, SDL Trados, across or Wordfast. These tools insulate tags and other untouchable elements from even novice translators.

We've marveled at how many search engine queries there are about localizing these projects, and we think that Robohelp and the other authoring environments have done a poor job explaining what's involved.

If you liked this article have a look at "Localizing Robohelp Projects."

If it isn't broken...break it!

What's the most effective way to bump up your translation costs unnecessarily?

Probably by localizing something that nobody will ever want in a foreign language, of course. But nobody would ever approve an expense like that, so it wouldn't have the opportunity to affect your translation costs.

There's a much sneakier, more pernicious way of wasting translation money: Tinkering with the original text (for example, English).

Suppose you localized your product or documentation from 2002 through 2007. You'd have five years' worth of translation memory (TM) economies and glossary entries going for you, with thousands of exactly matched words that incurred no translation cost from one version to the next. Then suppose that someone decided in 2008 to go in and "clean up" the original English text to make it more "readable" or "user-friendly."

What do you think would happen the next time you handed off this content for TM analysis? Suddenly, non-matches would pop up where exact matches used to be. Among the causes:

• Combining short sentences together
  
• Breaking long sentences apart
• Making stylistic changes to common terms (e.g., changing "phone" to "telephone" or "handset")
• Standardizing disparate terms (e.g., selecting one of "Proceed as follows," "Perform the following steps," "Following is the required procedure" and propagating throughout the documentation)
• Typographical or grammatical corrections
  

You might tolerate these modifications in the interest of improving your product in all languages - not just English - but the sad truth is that you may find that they make no difference in the localized products. You'd pay for words that the translator did not need to touch. This is an unfortunate artifact of the way in which translation jobs are estimated, but the analysis software cannot predict that the changes will make no difference to the translation; only the translator sees that.

Note that re-organizing content should not cost you additional translation money; as long as the sentence is the same (i.e., an exact match), it doesn't matter where it's located in the product.

So, are you better off leaving errors and other undesirables in your original-language content? No. It would be a mistake to let concern for translation cost impede your product improvement effort, like having the tail wag the dog. Still, to the extent you can control it, you should try to avoid purely stylistic changes that make no difference in how your customers use your product. A good editor can make a hundred such changes per hour, not realizing the ramifications on translation costs.

If you learned something from this post, you might like to read Improved Docs through Localization or Getting the Writers to Care about Localized Documents.

Whaddya know? They asked me first this time!

Do you spend a lot of your time running to catch up to the train? Have you ever been surprised in the middle of a meeting by project plans that were well underway with no thought given yet to localization? Are you getting used to it?

What if they asked you first (or at least early on) about the project's implications for internationalization and localization? Would you know how to react?

This certainly caught me by surprise a few months ago. A client called me in for consultation. He didn't want me to manage the upcoming localization of his user manuals; he wanted me to review and edit the English versions so that they would be ready to localize.

This client, though small, is enlightened. The company is selling English, French, German, Spanish and Japanese versions of several products, and it has a hand-in-glove relationship with its localization company. It knows where its global bread is buttered.

I jumped at the chance to work with people thinking this far in advance, so I reviewed the manuals and submitted changes, almost all of which were acceptable.

How can you review/edit documentation with an eye to translating it?

1. Take advantage of redundancy. Ensuring that identical sentences and paragraphs remain identical is a good way to lower per-word translation costs. Turn the text into a bookmark at its first occurrence, then invoke or cross-reference that bookmark at subsequent occurrences.
2. Ensure that the product matches the documentation. Not all organizations get around to this, believe it or not, and it becomes a bit of value added by the internationalization/localization function.
3. Standardize terms. Especially in companies without a well developed team of writers, manuals end up with pairs or trios of synonyms that will vex translators and add no information, so take the liberty of eliminating one in favor of the other:
   
   • Determine/specify
     
   • based on/according to
   • click the button/click on the button/select the button
   • lets you/enables you to/allows you to
4. Mention errors and inconsistencies that have nothing to do with internationalization. Again, you increase the perceived value of the localization function. Even though the result doesn't affect the localized products, the Localization Department (you) are contributing to a better core product.
5. Axe a few "dead" words. They add little to the explanation, will probably not survive translation, and inflate wordcount:
   
   • unique
   • basically
   • popular
   • congratulations
   • very much
     

By the way, the review took longer than I'd anticipated, so if you have a similar opportunity, don't bid a flat fee the first time.

Interested in this topic? Have a look at Improved Docs through Localization.

Getting the Writers to Care about Localized Documents

Do your technical writers go through the localized documents before handing them off to production?

I thought not.

It is, of course, just one more thing on a writer's already crowded list of things to do. Add to that the appeal for the writer of going through a book in a language of which s/he has probably no notion, and you have a recipe for can't/won't/don't want to.

You can go through it yourself, localization manager that you are, and you'll probably find a few things wrong. But the writers are looking for very different things, and they have a talent for spotting them immediately. If you can get your writers around the corner on the inconvenience of the exercise, you'll find that they add real value. The movement into and out of translation software can break things in a large document, and who better to detect such things - even with no more than a cursory overview - than the people who wrote the book in the first place?

I've seen writers go through translated versions of their documents and find:

• unexplained typeface changes
• broken or dead hyperlinks
• missing callouts
• untranslated text
• incorrect document part numbers
• corrupted graphics
  

The real showstopper, though, occurs at the end of a two-month translation cycle for a 300-page manual, when the writer spends ten minutes going through the book, then sends you e-mail that reads, "Nice job on the Chinese manual, but you got the wrong version translated."

Maybe not the optimal time to find this out, but once again: Who besides the writer would have caught this?

Translators - The Tech Writer's Best Friend/Worst Enemy

"Say, Jean, the translators found some problems with the original English documentation your team wrote. Do you want me to send you the corrections?"

"Sure, John. Do you want me to send you a nice cartridge of mustard gas?"

I never find that writers embrace the feedback from translators. It's not that the translators go out of their way to find errors; mostly it's that they don't understand the term/phrase/sentence/paragraph and cannot therefore translate it. This is the fundamental test of documentation usability - are you conveying your idea to the reader? - and most writers get grumpy when they don't pass it with flying colors.

It's also not the case that translators get snooty about the errors they find. In fact it's I, not the translators, who add a thin veneer of snootiness to the comments I send to the writers.

• Why are all of these Copy(1) and Copy(2) files in the RoboHelp project? Do we need them? Should we translate them?
• The FrameMaker files you gave us don't match the PDF you gave us. Which one is correct? (To their credit, most translators won't take for granted that the one with the later date stamp is the definitive source.)
• This training manual is for version 5.3. The last version of the software that we translated was 5.1. What has changed in the software? Do we need to translate the delta first, in order to translate the manual properly?
• We found 136 pages in the online help file with no content in them. Are they meant to be that way, or did something go wrong in the extraction process?
  

Writers don't often like to hear such feedback, but, if it's implemented, nobody can deny that it makes the books better.