dita translatability best practices
DESCRIPTION
DITA is not only great for technical writing, it’s 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.TRANSCRIPT
DITA translatability best practices
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
Brought to you by
@Fantpmas from
@YamagataEurope
Yamagata Europe
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
We write We translate We do the layout We print We package & ship We create software
I support
I know XML
I know RegEx
I know tools
I manage QA Distiller
I troubleshoot
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
They're in there for a friggin reason
Use DITA's internationalisation attributes
xml:lang
dir
translate
Use the translate attribute to make everyone
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
YES = YES NO = NO
Don't mention <term translate="no">Project X</term> to my mom.
Use the xml:lang attribute to identify language
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
<section id="Magritte" xml:lang="fr"> <title>Consignes de sécurité</title>
<p id="A">Danger, ceci n'est pas une pipe</p>
Use the dir attribute for LTR/RTL content
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
The title is "<term dir="rtl" xml:lang="ar"> !مفتاح معايير الويب </term>" in Arabic.
Tag your terminology
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
And I mean it!
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
Important terminology is identified
Ability to lock / unlock terms
Automatic term extraction
Automatic quality control
Key benefits
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
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
Use the conref attribute wisely
Or it will come back to haunt you
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
Use conrefs for complete sentences
<result>The suspect is apprehended.</result> <postreq>
<note conref=”reuse.dita#reusablephrases/ReadRights”/> </postreq>
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
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
Resolve or flatten conrefs prior to translation
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
Write stand-alone units of text
Not only great for re-use, but
Translators will you
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
Traditional book order is gone
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
Mind the spaces
Click·<uicontrol>Start·</uicontrol>to·shut·down.
Druk·op·<uicontrol>Start</uicontrol>om·af·te·sluiten.
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
Provide reference material
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
Do it for your own sanity
but also for the translators
Annotate where needed
• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com
<!- - 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
Conclusions
DITA provides excellent mechanisms to remove doubt
Be careful with conrefs
KISS