DITA translatability best practices

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