Best practices in internationalizing text with lots of markup?

Question

I'm working on a web project that will (hopefully) be available in several languages one day (I say "hopefully" because while we only have an English language site planned today, other products of my company are multilingual and I am hoping we are successful enough to need that too).

I understand that the best practice (I'm using Java, Spring MVC, and Velocity here) is to put all text that the user will see in external files, and refer to them in the UI files by name, such as:

#in messages_en.properties:
welcome.header = Welcome to AppName!

#in the markup
<title>#springMessage("welcome.header")</title>

But, having never had to go through this process on a project myself before, I'm curious what the best way to deal with this is when you have some segments of the UI that are heavy on markup, such as:

<p>We are excited to announce that Company1 has been acquired by
<a href="http://www.companydivisionx.com" class="boldLink">Division X</a>,
a fast-growing division of <a href="http://www.company2.com" class="boldLink">Company 2</a>, Inc. 
(Nasdaq: <a href="http://finance.google.com/finance?q=blah" class="boldLink">BLAH</a>), based in...

One option I can think of would be to store this "low-level" of markup in messages.properties itself for the message - but this seems like the worst possible option.

Other options that I can think of are:

• Store each non-markup inner fragment in messages.properties, such as acquisitionAnnounce1, acquisitionAnnounce2, acquisitionAnnounce3. This seems very tedious though.
• Break this message into more reusable components, such as Company1.name, Company2.name, Company2.ticker, etc., as each of these is likely reused in many other messages. This would probably account for 80% of the words in this particular message.

Are there any best practices for dealing with internationalizing text that is heavy with markup such as this? Do you just have to bite down and bear the pain of breaking up every piece of text? What is the best solution from any projects you've personally dealt with?

Answer 1

Typically if you use a template engine such as Sitemesh or Velocity you can manage these smaller HTML building blocks as subtemplates more effectively.

By so doing, you can incrementally boil down the strings which are the purely internationalized ones into groups and make them relevant to those markup subtemplates. Having done this sort of work using templates for an app which spanned multi-languages in the same locale, as well as multiple locales, we never ever placed markup in our message bundles.

I'd suggest that a key good practice would be to avoid placing markup (even at a low-level as you put it) inside message properties files at all costs! The potential this has for unleashing hell is not something to be overlooked - biting the bullet and breaking things up correctly, is far less of a pain than having to manage many files with scattered HTML markup. Its important you can visualise markup as holistic chunks and scattering that everywhere would make everyday development a chore since:

• You would lose IDE color highlighting and syntax validation
• High possibility that one locale file or another can easily be missed when changes to designs / markup filter down

Breaking things down (to a realistic point, eg logical sentence structures but no finer) is somewhat hard work upfront but worth the effort.

Regarding string breakdown granularity, here's a sample of what we did:

    comment.atom-details=Subscribe To Comments
    comment.username-mandatory=You must supply your name
    comment.useremail-mandatory=You must supply your email address 
    comment.email.notification=Dear {0}, the comment thread you are watching has been updated.
    comment.feed.title=Comments on {0}
    comment.feed.title.default=Comments
    comment.feed.entry.title=Comment on {0} at {1,date,medium} {2,time,HH:mm} by {3}


    comment.atom-details=Suscribir a Comentarios
    comment.username-mandatory=Debes indicar tu nombre
    comment.useremail-mandatory=Debes indicar tu direcci\u00f3n de correo electr\u00f3nico
    comment.email.notification=La conversaci\u00f3n que estas viendo ha sido actualizada
    comment.feed.title=Comentarios sobre {0}
    comment.feed.title.default=Comentarios
    comment.feed.entry.title=Comentarios sobre {0} a {1,date,medium} {2,time,HH:mm} por {3}

So you can do interesting things with how you string replace in the message bundle which may also help you preserve it's logical meaning but allow you to manipulate it mid sentence.