I am not convinced that the arguments behind the recommendations offered under the community docs Dynamic or static links and HTML in translatable strings regarding use of placeholders for links in translatable text apply well in all cases. We are told that this is bad:

Bad examples:

..
$BAD_INTERNAL_LINK = t('To get an overview of your administration options, go to !administer in the main menu.',
array('!administer' => l(t('the Administer screen'), 'admin'),

There seem to be 2 main arguments against this.

The 1st I accept in some cases:

The link text then becomes isolated, not part of the flow of the sentence at all. This is a big problem for translation.

Sometimes one needs the context to be able to translate the link title, but not always; sometimes the link title is clear anyway, and then I feel the above form should be permitted. (In the example, I agree that 'the Administer screen' might in rare cases cause confusion, but not all link titles do.)

The 2nd I disagree with:

.. the translator has no idea that a link is happening behind the placeholder, let alone the text of the link, so translation combinations from such solutions tend to be funny instead of professional.

That's easily solved by simply using something like this, with '@link-' in the placeholder name, which could become an acceptable convention:

$CLEAR_INTERNAL_LINK = t('To get an overview of your administration options, go to @link-administer-screen in the main menu.',
array('@link-administer-screen' => l(t('the Administer screen'), 'admin'),

I certainly don't agree that the above is worse (in all cases) than having quite complex HTML markup included in the string to translate like this:

Good examples::

..
$internal_link = t('To get an overview of your administration options, go to <a href="@administer-page">the Administer screen</a> in the main menu.',
array('@administer-page' => url('admin'),
));

Feedback and discussion welcome.

Comments

webel’s picture

I find this argument more compelling:

Our good examples keep the link markup in the text, so that translators are aware of what is happening, and the link text is also there to translate in the sentence flow. This lets them move the link around, if the language at hand requires it, move out text from the link or vice versa.

But I still find the "good example" rather ugly and error prone. I can't help thinking that there must be a better 3rd way, perhaps a new placeholder system/indicator dedicated to links (after all the WWW uses a lot of them).

Webel IT Australia, "Elements of the Web", Scientific IT Consultancy,
For PHP-driven Drupal CMS web sites, Enterprise Java, graphical UML, UML Parsing Analysis, SysML, XML.

webel’s picture

From https://www.drupal.org/node/322774:

.. another best practice is naming the placeholders properly. The bad examples use !handbook and !administer which gives no clear indication of what is going behind them. Better examples are @drupal-handbook and @administer-page. If you have multiple links in one string, just don't do @url1, @url2 and so on, since when translators move things around, or when you need to add a new link inbetween the two, it just does not work. More descriptive names are better for you and for translators alike.

Then why not use @url-drupal-handbook and @url-administer-page ?

Webel IT Australia, "Elements of the Web", Scientific IT Consultancy,
For PHP-driven Drupal CMS web sites, Enterprise Java, graphical UML, UML Parsing Analysis, SysML, XML.