DITA translatability best practices
1 like1,073 views
DITA is not only great for technical writing, its great for translation too. Amongst other things, DITA provides great mechanisms to instruct translators on what to translate and what not. It also provides a clear way to tag terminology. However, there are some pitfalls to be aware of like excessive use of conrefs.
DITA translatability best practices
- 1. DITA translatability best practices Brought to you by @Fantpmas from @YamagataEurope ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 2. Yamagata Europe We write I support We translate I know XML We do the layout I know RegEx We print I know tools We package & ship I manage QA Distiller We create software I troubleshoot ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 3. Use DITA's internationalisation attributes xml:lang dir translate They're in there for a friggin reason ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 4. Use the translate attribute to make everyone YES = YES NO = NO Don't mention <term translate="no">Project X</term> to my mom. ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 5. Use the xml:lang attribute to identify language <section id="Magritte" xml:lang="fr"> <title>Consignes de s辿curit辿</title> <p id="A">Danger, ceci n'est pas une pipe</p> ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 6. Use the dir attribute for LTR/RTL content The title is "<term dir="rtl" xml:lang="ar">!惠悋忰 惺悋惘 悋惡 /term>" in Arabic. < ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 7. Tag your terminology And I mean it! ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 8. Key benefits Important terminology is identified Ability to lock / unlock terms Automatic term extraction Automatic quality control ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 9. Click <uicontrol>Configure</uicontrol>. Configure the options to your wish. Press <uicontrol class="Windows">Select</uicontrol> to browse to the file. Choose <uicontrol class ="QA Distiller">Select</uicontrol> to add a file. ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 10. Use the conref attribute wisely Or it will come back to haunt you ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 11. Use conrefs for complete sentences <result>The suspect is apprehended.</result> <postreq> <note conref=reuse.dita#reusablephrases/ReadRights/> </postreq> ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 12. Avoid using conrefs for common nouns Using a <keyword conref=tools.dita#tools/Crowbar/>, remove the Dragon spacecraft from the ISS. Adding <keyword conref=servers.dita#servers/Fileserver/>s is easy. Big no no ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 13. Resolve or flatten conrefs prior to translation ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 14. Write stand-alone units of text Not only great for re-use, but Translators will you ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 15. Traditional book order is gone ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 16. Mind the spaces Click揃<uicontrol>Start揃</uicontrol>to揃shut揃down. Druk揃op揃<uicontrol>Start</uicontrol>om揃af揃te揃sluiten. ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 17. Provide reference material ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 18. Annotate where needed Do it for your own sanity but also for the translators ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 19. <!- - Some mumbo jumbo legacy code, don't touch or universe will implode - -> <draft-comment author="EBP" disposition="completed">This section deals with our other top-secret project</draft-comment> <note type="other">This stuff is important as this is the abstract sent to our CEO (and he has no sense of humour)</note> ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com
- 20. Conclusions DITA provides excellent mechanisms to remove doubt Be careful with conrefs KISS ≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒≒ www.yamagata-europe.com