Download pdf - DITA translatability best practices

DITA translatability best practices

• • • • • • • • • • • • • • • • • • • • www.yamagata-europe.com

Brought to you by

@Fantpmas from

@YamagataEurope

Yamagata Europe


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


They're in there for a friggin reason

Use DITA's internationalisation attributes

xml:lang

dir

translate

Use the translate attribute to make everyone


YES = YES NO = NO

Don't mention <term translate="no">Project X</term> to my mom.

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>

Use the dir attribute for LTR/RTL content


The title is "<term dir="rtl" xml:lang="ar"> !مفتاح معايير الويب ‎<‎/term>" in Arabic.

Tag your terminology


And I mean it!


Important terminology is identified

Ability to lock / unlock terms

Automatic term extraction

Automatic quality control

Key benefits


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.


Use the conref attribute wisely

Or it will come back to haunt you


Use conrefs for complete sentences

<result>The suspect is apprehended.</result> <postreq>

<note conref=”reuse.dita#reusablephrases/ReadRights”/> </postreq>


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


Resolve or flatten conrefs prior to translation


Write stand-alone units of text

Not only great for re-use, but

Translators will you


Traditional book order is gone


Mind the spaces

Click·<uicontrol>Start·</uicontrol>to·shut·down.

Druk·op·<uicontrol>Start</uicontrol>om·af·te·sluiten.


Provide reference material


Do it for your own sanity

but also for the translators

Annotate where needed


<!- - 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>


Conclusions

DITA provides excellent mechanisms to remove doubt

Be careful with conrefs

KISS