Bryan Tipper

By Peter Fournier
“Plan early, plan thoroughly”

Planning for translation

Joann Hackos, Grande Dame of DITA, claimed in 2011 that just switching to DITA could save 20% on translation costs. A competent Content Management System could easily save another 20% (Joann Hackos’ Keynote on DITA and Translation Management).

If you need translation or localization, DITA seems like a slam dunk decision. Might as well get started with DITA in English and develop the translation part later, yes?

No, don’t do that. You really must plan to include translation into your DITA workflow from the start or you can fail to deliver the expected cost savings promised at the start of the migration to DITA project.

 

Basic issues

The translation and localization industry has migrated to its own XML standards. There are several:

• XLIFF (XML Localization Interchange File Format)
• TMX (Translation Memory eXchange)
• TBX (TermBase eXchange)
• SRX (Segmentation Rules eXchange)
• ITS (Segmentation Rules eXchange)
• and no doubt others …

All of these standards play well with DITA but can also play very badly depending on the tools, workflow, CMS or CCMS and outside suppliers you will use in your implementation of DITA + translation.

This diagram shows some of the complexities involved in an integrated workflow.

Without translation the diagram looks more like this:

So, is this complexity of translation good news or bad news? It’s excellent news with proper planning. What are the steps required to achieve excellent results?

 

Step One: It’s been done before …

DITA plus translation has been done before. Seek out others who have already implemented the transition. You will find that there are many ways to approach the problem. Some of the ways will be similar to your situation, others won’t be, but the more people you talk to the more ideas you’ll have to work with.

 

Step Two: Talk to translation companies

Before talking with a translation company, you need to prepare a sample of your content, in DITA, that represents the full scope of the content you will want translated. To keep all conversations on track you likely want to use the same sample you use for testing Stilo Migrate and OptimizeR.

Talk to several companies. You will find each one has different procedures, tools, and content specialties. You are looking for the company with the best fit with DITA, your content, and the capacity for the expected translation load. To minimize the technology load at your end you will most likely want to deal with a company that can handle DITA as the input to translation workflow.

However, some translation companies require XLIFF files as input to the process. If XLIFF is required ask the company about handling the conversion from DITA to XLIFF and back again. If you must generate XLIFF internally there are tools, like Fluenta, that may enable the conversion in both directions reliably.

One of the features you will want to explore with these suppliers is “translation memory”. Modern translation software can remember what has not changed and so does not need to be translated again. However, this memory can be complicated. Can I send the DITA files for an 800-page book to the supplier and expect them to manage the translation memory? Some CCMS’ and CMS’ can handle sending just the changed files. Does that fit in with the translation supplier’s workflow?

 

Step Three: Talk to Component Content Management System (CCMS) and Content Management System (CMS) companies

If you are already using a CCMS or CMS you may find the system is already optimized for efficient translation from a DITA source.

If you are in the market for a CMS or CCMS pay close attention to how the system will help you manage translation. Some systems can deal directly with translation companies over the internet.

In the pilot phase of a migration to DITA plus translation you likely don’t need a CMS or CCMS right away; you can use the file system instead. Using the file system in the early stages has two main advantages. The first is that it’s easier to conceptualize how all the pieces fit together before introducing a database system — it aids in learning. This will be a benefit when selecting a CCMS or CMS. Second, it makes interaction with outside suppliers easier; ZIP a folder with your content and send it out for review and discussion.

Here’s a typical folder structure for DITA in the filesystem:

 

Step Four: Translation companies have important things to say about writing

Translation may be necessary but is never easy. Ask your translation supplier(s) for advice on how to write English content that makes good translation possible. Grammar varies dramatically from language to the next. For example, in French tables are feminine but floors are masculine. In English tables and floors have no gender. That’s a trivial example. Apparently Finnish has 15 inflections for nouns. This thread, Product names and reuse: a very serious anti-pattern when translating documents, on the OASIS site gives an excellent summary of some of the problems related to DITA reuse. In other words, authoring, at the most basic level, can make translation more expensive. Be sure to explore this issue with potential translation suppliers.

 

Step Five: Translation companies have important things to say about DITA

Reuse, especially the more advanced reuse options in DITA, can cause problems and expense during translation. CONREF, DITAVAL, CONKEYREF, HREF all have special caveats when interacting with translation companies. It’s important to understand these limitations and opportunities before committing to a flavor of DITA or a specific translation partner.

 

Step Six: Start small

Back in step two I recommended developing a representative sample, in DITA, of your content. Use and refine that sample in all your dealings with suppliers. Having all the conversations based on the same sample will make the final choices much easier.

Starting small also has the benefit of making mistakes easier to fix. Just like Stilo Migrate‘s ability to let you iteratively approach the perfect migration from MS Word, say, to DITA, a good sample of content will allow you to manage the iterative approach to a complete DITA plus translation system in your company.

 

Conclusion

Converting from a legacy authoring platform to DITA is one thing, converting to DITA plus translation is entirely different. Suddenly you are not trying to optimize for internal requirements but internal and external optimizations simultaneously. The more planning you can do for this external and internal optimization the better. It may add six months to the planning phase of a transition to DITA but will pay off big time in avoided costs and maximized efficiency.

 

Not recommendations but good sources …

The following are the best sources of general information on translation I’ve found this week. Please don’t take these links or other links above as recommendations! They’re just good information I’ve found.

How To Translate DITA Projects [Step-By-Step Guide]

Translating your DITA Project

 

About the Author

Peter Fournier has extensive experience in the BNR/Nortel documentation space. In the late 80’s and early 90’s he studied the feasibility of moving the Technical Documentation to SGML. He later developed, with his team and advanced online help system for Network Management and other software produced by Nortel. The core of the online help software was based on SGML principles of containerization but only had five or six base elements, and a lot of attributes.  It was engineered to be compatible with SGML so the group had no trouble generating valid XML when the draft standard appeared in late 1996 or early 1997.  In 2005 he discovered, with great joy, DITA XML. He introduced DITA to JDSU (now Lumentum) in 2008 and served as DITA manager and technical prime until 2018.  Between 2010 and 2014 he  also found  time to get a startup going and developed software to assist groups of 1 to 20 people to get into DITA and manage all the background complexity, including publication.  As of 2021 he’s back in the DITA space and loving the Stilo philosophy of making highly complex transformation software easily accessible to customers.

By Peter Fournier

DITA XML conversion projects can fail simply because they get too complicated. Major stumbling blocks leading to complexity include:

• Too many styles, sometimes running into the hundreds in large document suites.
• Badly applied styles for example a “Heading 1” followed by a “Heading 4”.
• A “Normal” paragraph manually formatted to look like something else.
• Inconsistent content such as multiple ways to label procedures, for example “To clean XYZ” and “Cleaning XYZ”.

Because of these and many other problems it has been very common to cleanup a suite before converting to DITA XML and often doing post-conversion cleanup as well. Pre- and post-cleanup can be the most time consuming, complex, hard to manage and expensive part of a conversion project.

Enter Stilo’s Migrate software. For instance, suppose we have a list in a document that looks like this:

In Microsoft Word, or any other WYSIWIG editor, all the program knows is that

• this text contains a heading (maybe),
• paragraphs, some of which are in a numbered list,
• and formatting to make the text look the way it does.

Migrate assists in the automated conversion to DITA XML by helping you create conversion rules and enhance the final DITA XML output.  For example, you can create:

1. A rule that detects the fact that the first word in the heading ends in “ing”, indicating it is probably a task heading. It, and the subsequent text will be placed in a “task” topic. The paragraph will be placed in a “title” element.
2. However sometimes a heading isn’t really a heading it just looks that way, it’s a manually formatted “Normal” paragraph. That’s OK.  You can create a rule that detects the manual formatting and the applies rule 1 above.
3. A rule that adds a registered trademark symbol to the first occurrence of the word “QuickTrace”.
4. A rule that detects that some paragraphs are numbered and that these should be wrapped in “steps/step/command” elements.
5. A rule that detects that the word following the word “Click” is likely a UI element. The word following “Click” will be wrapped in a “uicontrol” span.
6. However, sometimes the word “Click” is followed by a word that is in turn followed by a “→” character in which case the whole string with embedded arrows will be wrapped in “menucascade/uicontrol” elements.
7. A rule that detects that a paragraph before the actual steps should be wrapped in a “context” element.
8. A rule that detects that the last paragraph is indented at the same level as the numbered list and is not followed by another list item. Therefore, it should be wrapped in a “result/p” element.

The final result of the conversion to DITA will look like this:

So, starting with just formatted paragraphs you can create enriched, valid DITA XML, as you can see in the picture — and avoid, perhaps eliminate, pre- and post-cleanup.

To get a better idea of just how enriched the DITA XML really is here is the file that generated the improved output:

Note that the “→” character isn’t present in the XML, it’s added as part of generating the output.

The next time Migrate encounters a task formatted this way it will know what to do. That makes your conversion project simpler, more accurate and faster as you go along.

 

About the Author

Peter Fournier has extensive experience in the BNR/Nortel documentation space. In the late 80’s and early 90’s he studied the feasibility of moving the Technical Documentation to SGML. He later developed, with his team and advanced online help system for Network Management and other software produced by Nortel. The core of the online help software was based on SGML principles of containerization but only had five or six base elements, and a lot of attributes.  It was engineered to be compatible with SGML so the group had no trouble generating valid XML when the draft standard appeared in late 1996 or early 1997.  In 2005 he discovered, with great joy, DITA XML. He introduced DITA to JDSU (now Lumentum) in 2008 and served as DITA manager and technical prime until 2018.  Between 2010 and 2014 he  also found  time to get a startup going and developed software to assist groups of 1 to 20 people to get into DITA and manage all the background complexity, including publication.  As of 2021 he’s back in the DITA space and loving the Stilo philosophy of making highly complex transformation software easily accessible to customers.

By Peter Fournier

So, you’re convinced that moving your documentation to DITA XML is a great idea.  The move will increase productivity, enable reuse and allow multichannel publishing to many platforms.  It will also future proof your authoring and publishing – no more getting captured by tool vendors!  Yeah!

But converting your existing documents to DITA can be a daunting task. Documentation is likely the messiest data ever created. It’s very common to discover that all those MS Word documents that should be moved to DITA are not identical from a data point of view:  different documents use different styles, very often headings are actually “Normal” but manually formatted to look like a heading, a numbered list can be a procedure in one place or just a list in another.   From a structured authoring point of view, source documents written in WYSIWYG tools are not your friend.

Because of the complexity of source documents, companies moving to DITA usually choose to get some help getting from a legacy authoring tools into DITA.  There are several routes to choose from:

1. Over-the-wall conversion
   Send your documents to a company specializing in conversion. They take your documents, convert them, then send them back for QA.  The QA usually involves several conversion and refinement cycles before achieving acceptable results.
2. In-house conversion with the help of consultants
   This can deliver better results faster if only because it facilitates QA, conversation, discussion and exception handling. Unfortunately, when the consultants leave they take with them the knowledge of exactly how the work was done. You lose precious conversion experience that could have been used in your next project.
3. In-house conversion using off-the shelf tools
   This can be an excellent solution since you retain the knowledge of how to convert documents to DITA and making the next 1,000 pages of conversion easier to do. Unfortunately, off-the-shelf tools often require expensive cleanup of the source documents and are not sophisticated enough to do a complete conversion, including advanced DITA features, all in one go.

Taking control with Stilo’s Migrate

Migrate smooths the path from messy WYSIWYG documents to advanced DITA XML. Here’s how.

1. Migrate has the same advantages as over-the-wall conversion
   You upload your documents to Migrate in the cloud and convert them there with help from Migrate/DITA experts. They will assist you with initial conversions and you always pay a fixed rate per thousand words per document. Subsequent cycles through the conversion process are free, in-house, and fast – refine and QA as much as you need, for free.
2. Migrate has the same advantages as working with consultants
   Stilo’s business model is not about charging per hour as though they were normal conversion consultants. No, Stilo’s business model is assisting you to become your own conversion expert while always being available in the background to help with difficult problems. There is a consulting fee to be paid but it’s not a long term-contract for a fixed amount – you only pay Stilo for the consulting you require to get passed the sticky bits.
3. Migrate has the same advantages as using off-the-shelf tools
   Migrate has more depth and capability built-in than any other off-the-shelf tool. This minimizes the amount of cleanup required before conversion and enables conversion to DITA with advanced features. Also, Migrate captures the process for converting documents in “rule sets”. Any one rule set can be applied to any number of documents.  So, documents from a specific group or year in your company might require different conversion rules than documents from another group or year.  That’s fine.  Rule sets allow you to permanently capture all of the learning and knowledge about conversion as you go along.

Control achieved!

Stilo’s Migrate is unique in the industry.  It is finely tuned, based on extensive experience over 30 years, to satisfy real business objectives. Among them are:

1. Proof of concept before commitment
   Migrate allows companies to start their migration to DITA with small bite-sized projects done for minimal cost. If the project is successful companies can expand to larger document suites without entering a new project or dealing with a new company.  Rule sets guarantee capturing experience in-house so that what is learned in converting 30 pages can be applied and refined in the next 100 pages, the next 1,000 pages, and the next 10,000 pages or more. Migrate scales very well within typical budget processes. This is budget control.
2. Project management
   Stilo’s Migrate model fits in well with standard SW project management. In the last 1,000 pages converted did we experience more or less requirement for consulting with Stilo experts? In the last thousand pages did we have to create new rules at a higher or lower rate than the previous 1,000 pages?  These measures are very similar to standard SW measures such as defects per thousand lines of code.  This is project control.
3. Source coverage
   You have to convert source documents saved in DOCBOOK, HTML, HTML5, DOCX and MIF. Can Stilo handle all these sources? Yes, of course.  This is technology control.
4. Learning and knowledge capture
   Are we climbing the corporate knowledge ramp? Can we see our way to no longer needing hand holding from Stilo?  Of course.  That is the Stilo business model.  This corporate business intelligence control.

Control comes in many flavors and at different levels in a company. Stilo’s Migrate helps achieve control at every level.

 

About the Author

Peter Fournier has extensive experience in the BNR/Nortel documentation space. In the late 80’s and early 90’s he studied the feasibility of moving the Technical Documentation to SGML. He later developed, with his team and advanced online help system for Network Management and other software produced by Nortel. The core of the online help software was based on SGML principles of containerization but only had five or six base elements, and a lot of attributes.  It was engineered to be compatible with SGML so the group had no trouble generating valid XML when the draft standard appeared in late 1996 or early 1997.  In 2005 he discovered, with great joy, DITA XML. He introduced DITA to JDSU (now Lumentum) in 2008 and served as DITA manager and technical prime until 2018.  Between 2010 and 2014 he  also found  time to get a startup going and developed software to assist groups of 1 to 20 people to get into DITA and manage all the background complexity, including publication.  As of 2021 he’s back in the DITA space and loving the Stilo philosophy of making highly complex transformation software easily accessible to customers.