Internationalisation of documentation links

As the various localisations of CiviCRM get traction, the first localised versions of documentation pages begin to show up – and this brings us to the issue of how to internationalise these of the CiviCRM strings (texts) that contain links to documentation pages so that when a given string is translated to, say, German, it also refers to the German version of the documentation page (if such is present). For previous and current CiviCRM versions (including the upcoming CiviCRM 2.2), when we internationalised a string, we wanted to leave the link to the documentation page outside of the string, like this: {ts 1=http://wiki.civicrm.org/…}Read more at %1{/ts}. This approach has two major benefits:

• The translators are not bothered to retype the link letter-to-letter in their translations (any errors here would mean that the link stops working), and
• if the link ever changes, the string (‘Read more at %1’) doesn’t, and the translators don’t have to re-translate it.

Unfortunately, this approach also means that the links themselves are not internationalised and can’t be localised; the %1 in the translation always gets replaced by the link to the American English documentation. As we still believe in the validity of both of the above benefits, we didn’t want to bring the links back into the string. Instead, we propose the following for CiviCRM 2.3:

• The code gets changed to {ts link=http://wiki.civicrm.org/…}Read more at %link{/ts}, i.e., the 1 gets replaced with link,
• the translators still see the ‘Read more at %link’ texts and so aren’t bothered with link maintenance,
• there is a separate PO file provided for each language, civicrm-links.po, which gathers all the links defined in this way inside the {ts} and ts() calls.

This way, thanks to the civicrm-links.po files, every language can maintain ‘translated’ links in a separate place from the actual strings referring the links. This means that the strings don’t change when the links do, while at the same time every language can maintain a separate lists of documentation pages that are translated into the given language (and the mechanism will fall back to the default American English pages if the given page is not localised into the language at hand). In the future, if we somehow manage to tell Confluence (our wiki engine) to link the localised pages as being related to the original, the civicrm-links.po files could be even generated automatically. The issue tracking the implementation of the above solution is CRM-3941. Thanks for reading and please share any comments you might have on the above solution. :)